Calling Subroutines and TCL Commands on MultiValue Databases from OpenInsight

OpenInsight provides two functions that will allow developers to call a subroutine or execute any TCL command on a multivalue database server such as Universe, Unidata, D3 or QM.

Description

MVBFS_SUBCALL is a function added in OpenInsight 9.4 to allow developers to call a subroutine on the multivalue server.

Function MVBFS_SUBCALL(ConnectionName, SubName, ParamCount, P1, P2, P3, P4, P5, …, P30)

The function has the following parameters:

Parameter	Description
ConnectionName	(in) MV Volume ( Connection ) name
SubName	(in) Name of subroutine to execute
ParamCount	(in) Number of parameters expected by the subroutine (0-30)
P1 … P30	(in/out) Optional parameter values, default to ''

The called routine must be a cataloged subroutine on the server. On D3 servers the subroutine must be flashed compiled. If the called routine changes any parameter the calling routine can retrieve it.

Description

MVBFS_EXECPROC is a function added in OpenInsight 9.4 to allow developers to send any TCL command to the multivalue server and capture the response.

Function MVBFS_EXECPROC(ConnectionName, Command, Captured, Replies, Interactive)

The function has the following parameters:

Parameter	Description
ConnectionName	(in) Volume ( Connection ) name
Command	(in) The TCL command
Captured	(out) The output of the command, (e.g. what would appear on the screen in a terminal session
Replies	(in) Similar to a DATA statement, you can supply an FM delimited list of answers to expected prompts
Interactive	(in) Default is null, set to true if you want OpenInsight to put up a message box if the server prompts for data

 
 
 
Subroutine Test_MVBFS_Subcall( connection_name)
 
/*
 
**  Sample program showing how to interact with the server
 
**  By writing a record
 
**  Issuing a TCL command
 
**  Calling a program
 
**
 
** In this example we create the text for an OpenQM program
 
**  Write the text in the BP file on the server using WRITE_ROW
 
**  Issue commands to compile and catalog it using MVBFS_EXECPROC
 
**  Call the subroutine on the server with parameters using MVBFS_SUBCALL
 
02-10-12  rjc  Created
 
*/
 
$Insert msg_Equates
 
$Insert logical
 
$Insert vol_table_equates
 
$Insert SSPERRORS_600
 
Declare Function Msg, MVBFS_execproc, GET_STATUS
 
call Set_Status(0)
 
* Edit the volume id and program name to suit your needs
 
* The volume id is the connection name in the MVBFS_CONNECTION_DETAILS window
 
* If not passed in, for an existing connection
 
If Assigned(connection_name) Else connection_name =''
 
If connection_name #''  Then
 
Call Attach_table(connection_name,'' ,'' )
 
End else
 
Locate 'MVBFS' In @volumes(vol_file_sys$) Using @fm Setting pos Then
 
connection_name = @volumes(vol_location$)<pos,1>
 
end
 
If connection_name ='' Then
 
Msg(@window, 'Unable to determine the connection to use, terminating')
 
Return ''
 
end
 
end
 
*---
 
* Create an example program which will have two parameters
 
* The program will accept a value in the first parameter
 
* and return a modified value in the second parameter
 
* In real life you will call an existing catalogued program
 
* You can call any routine with 0 to 30 parameters
 
* You can pass data in and or out of any parameter
 
*---
 
* the name of the program
 
program_file = 'BP' ; * I ASSUME you have a BP file.  Change this to a different file as needed
 
program_name = 'OI_CLIENT' ;
 
* Define it
 
program_body = 'SUBROUTINE ':program_name:'(INPARAM, OUTPARAM)'
 
program_body<-1> = '* Test program to Demonstrate calling QM from OI'
 
program_body<-1> =''
 
program_body<-1> = 'OUTPARAM="YOU PASSED *" : INPARAM : "*"'
 
program_body<-1> = 'RETURN'
 
program_body<-1> = 'END'
 
* Write it to the server, don't bother to lock the record
 
lock_flag = 0
 
ssp_response =''
 
Call Write_Row(program_file, program_name, program_body, lock_flag)
 
Call Get_Status(ssp_response)
 
Call Set_Status(0)
 
If ssp_response<1,1> # SSP_ROW_WRITTEN_OK$  Then
 
Convert @fm To @vm In ssp_response
 
Msg(@window, 'Unable to write row ': @vm :  ssp_response)
 
Return ''
 
end
 
*---
 
* Compile it at the server using Execproc
 
*---
 
command = 'BASIC ' :program_file : ' ' : program_name
 
captured = ''
 
pReplies = ''
 
pInteractive = ''
 
result_code = MVBFS_execProc(connection_name, command, captured, pReplies, pInteractive )
 
If result_code eq -1 Then
 
Msg(@window, 'Unable to execute command ' : Quote(command) )
 
Return ''
 
End Else
 
Convert @fm To @vm In captured
 
def = ''
 
def<MCaption$> = 'Result of Catalog'
 
def<mText$> = captured
 
def<mIcon$> = 'I'
 
msg(@window, def)
 
End
 
*---
 
* Cataloged it now using execproc
 
* Note thst if you run the program multiple times QM will prompt "Do you want to Overwrite (Y/N)"
 
* So, pass a "Y" in pReplies, QM will use it as the answer
 
* If you expect multiple prompts, pass an @fm delimited string of answers
 
*---
 
command = 'CATALOG ' : program_file : ' ' : program_name
 
pReplies = 'Y' ; * provide a reply incase QM prompts about overwriting
 
result_code = MVBFS_execProc(connection_name, command, captured, pReplies, pInteractive )
 
If result_code eq -1 Then
 
Msg(@window, 'Unable to execute command ' : Quote(command) )
 
Return ''
 
End Else
 
Convert @fm To @vm In captured
 
def = ''
 
def<MCaption$> = 'Result of Catalog'
 
def<mText$> = captured
 
def<mIcon$> = 'I'
 
msg(@window, def)
 
End
 
*----
 
* In this example we have 2 parameters, passing data in the first, getting response from the second
 
*---
 
ParamCount = 2         ; * our example uses 2 parameters
 
inparam  = timedate()  ; * our example expects something in the first param
 
outparam = 'foo'          ; * our example expects nothing in the second param
 
Call MVBFS_Subcall(connection_name, program_name, ParamCount, inparam, outparam)
 
* echo the result
 
def = ''
 
def<MCaption$> = 'Result of Subcall'
 
def<mText$> = 'in=':inparam : @vm :'out=': outparam
 
def<mIcon$> = 'I'
 
msg(@window, def )
 
Return ''