skip to main content
OpenEdge Development: ADM Reference
Progress Dynamics Call Wrapper : API reference
 
API reference
This section provides details about the followihg APIs for the Progress Dynamics Call Wrapper and explains how each API procedure works:
*callstring.p procedure
*callstringtt.p procedure
*calltable.p procedure
*calltablett.p procedure
*cleanupCall procedure
*determineTableType function
*InvokeCall procedure
*obtainCallInfo function
*obtainParamPropValue function
*obtainProcHandle function
*setupTTFromSig function
*setupTTFromString function
*setupTTFromTable function
callstring.p procedure
External procedure that allows for a single RUN statement to invoke a call using a string that defines the parameters. The procedure is useful for minimizing the number of requests it takes to invoke a call on the AppServer.
All outputs and return values from the invoked procedure are available through the properties or parameters supplied as parameters.
Parameters:  
pcCallName INPUT CHARACTER
Name of an external or internal procedure or function to be invoked.
pcTarget INPUT CHARACTER
The name of a manager procedure, the filename of a relatively or absolutely pathed procedure, or an integer value that evaluates to a procedure handle. If the value of this parameter is "" or the Unknown value (?), by default, pcCallName contains the name of a procedure that is to be run nonpersistently.
The parameter is optional. If nothing is specified, then "" or the Unknown value (?) is passed.
pcTargetFlags INPUT CHARACTER
This parameter can contain modifiers that are used to invoke the persistent procedure. A modifier can be a valid combination of the following:
*P(ersistent) — Indicates that a new instance of the procedure should be instantiated persistently and left running.
*A(DM2) — Indicates that a new instance of an ADM2 procedure should be invoked persistently and the initializeObject internal procedure called to initialize it. The ADM2 procedure is left running after the call is complete.
*S(ingle) — Indicates that a new instance of the procedure should be instantiated if a running version is not found and left running.
*K(ill) — Indicates that if a procedure was instantiated during the call, it should be deleted before control is returned.
The default is to apply the behavior of the S parameter. That is, a persistent procedure is started if it is not found by walking the procedure stack and left running after the call is complete.
You can specify any of the P, A, or S modifiers in combination with K to shut down the procedure. For example, PK instructs the caller to instantiate a new instance of the procedure persistently and delete it when it is complete.
The parameter is optional. If nothing is specified, then "" is passed.
pcCallParmString INPUT CHARACTER
A string that contains the parameters to pass to the procedure or function that is being invoked. The string is a comma-separated list of parameters. Each parameter is a string consisting of space-delimited values in the form "mode data type parameter" where:
*mode is one of INPUT, OUTPUT, INPUT-OUTPUT, or OUTPUT-APPEND.
*data type is one of CHARACTER, DATE, LOGICAL, INTEGER, DECIMAL, RAW, HANDLE, or ROWID.
*parameter is the name of either a property that was previously set using setPropertyList or setSessionParam, or a single quoted constant. If a property is specified, the procedure attempts to evaluate the property value by calling getPropertyList. If no property is available, or Progress Dynamics is not running, a call is made to getSessionParam for the property value. If neither call succeeds, the unknown value is passed.
If the mode of the parameter is either OUTPUT or INPUT-OUTPUT, the property that is specified contains the output value from the call after the call is complete.
The parameter is optional. If nothing is specified, then "" or the Unknown value (?) is passed.
Notes:  
*Once the procedure finishes executing, all temporary handles are deleted and the ttCall record no longer exists for the call. As a result, the Progress Dynamics Call Wrapper has no information about this call so that there are no memory leaks created by calling callstring.p.
*If the mode of the parameter is OUTPUT or INPUT-OUTPUT and a property that was set using setPropertyList is specified, the value of the property is set on the server side. It is not synchronized with the client unless the entire call is executed on the client side.
callstringtt.p procedure
External procedure that allows a single RUN statement to invoke a call using a string that defines the parameters and pass up to 64 temp-tables. This procedure is useful for minimizing the number of request it takes to invoke a call on the AppServer.
All outputs and return values from the invoked procedure are available through the properties or parameters supplied as parameters.
Parameters:  
pcCallName INPUT CHARACTER
Name of an external or internal procedure or function to be invoked.
pcTargetObjec INPUT CHARACTER
Name of a manager procedure, the filename of a relatively or absolutely pathed procedure, or an integer value that evaluates to a procedure handle. If the value of this parameter is "" or the Unknown value (?), by default, pcCallName contains the name of a procedure that is to be run nonpersistently.
The parameter is optional. If nothing is specified, then "" or the Unknown value (?) is passed.
pcTargetFlags INPUT CHARACTER
This parameter can contain modifiers that are used to invoke the persistent procedure. A modifier can be a valid combination of the following:
*P(ersistent) — Indicates that a new instance of the procedure should be instantiated persistently and left running.
*A(DM2) — Indicates that a new instance of an ADM2 procedure should be invoked persistently and the initializeObject internal procedure called to initialize it. The ADM2 procedure is left running after the call is complete.
*S(ingle) — Indicates that a new instance of the procedure should be instantiated if a running version is not found and left running.
*K(ill) — Indicates that if a procedure was instantiated during the call, it should be deleted before control is returned. The default is to apply the behavior of the S parameter. As a result, a persistent procedure is started if it is not found by walking the procedure stack and is left running after the call is complete.
You can specify any of the P, A, or S modifiers in combination with K to shut down the procedure. For example, PK instructs the caller to instantiate a new instance of the procedure persistently and delete it when it is complete.
The parameter is optional. If nothing is specified, then "" is passed.
pcCallParmString INPUT CHARACTER
A string containing the parameters to pass to the procedure or function that is being invoked. The string is a comma-separated list of parameters. Each parameter is a string consisting of space-delimited values in the form "mode data type parameter" where:
*mode is one of INPUT, OUTPUT, INPUT-OUTPUT, or OUTPUT-APPEND.
*data type is one of CHARACTER, DATE, LOGICAL, INTEGER, DECIMAL, RAW, HANDLE, TABLE-HANDLE, or ROWID.
*parameter is the name of either a property that was previously set using setPropertyList or setSessionParam, or a single quoted constant that does not contain spaces or commas. If a property is specified, the procedure attempts to evaluate the property value by calling getPropertyList. If no property is available, or Progress Dynamics is not running, a call is made to getSessionParam for the property value. If neither call succeeds, the unknown value is passed.
If the mode of the parameter is either OUTPUT or INPUT-OUTPUT, the property that is specified contains the output value of the call after the call is complete. If the data type is either HANDLE or TABLE-HANDLE, the parameter can also be an integer value between 1 and 32 that maps to one of the tables passed in with the call.
The parameter is optional. If nothing is specified, then "" or the Unknown value (?) is passed.
pcHandlesToSkip INPUT CHARACTER
By default, the call wrapper does a DELETE OBJECT on tables that are listed in phCallTableHandle01 through 64 before returning. This avoids memory leaks caused by the duplication of temp-tables. In some cases, this behavior might be undesirable, such as when the table being returned is a Progress Dynamics temp-table that should be retained in the cache on the server.
To address this issues, this parameter allows a comma- separated list of numbers between 1 and 64 corresponding to the handles below. If a number is found in the list, the corresponding handle is not deleted in the procedure prior to control returning to the caller.
Note: Using an * in a CAN-DO list indicates that none of the handles should be deleted.
The parameter is optional. If nothing is specified, then "" is passed.
phCallTableHandle01 to phCallTableHandle64 INPUT-OUTPUT TABLE-HANDLE
A table-handle that needs to be passed into the call.
The parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
Notes:  
*Once the procedure finishes executing, all temporary handles are deleted and the ttCall record no longer exists for the call. As a result, the Dynamic Call Wrapper has no information about this call so that there are no memory leaks created by calling callstring.p.
*The caller is responsible for cleaning up phCallParmTT and phCallParmTH and the phCallTempTable or phCallTableHandle objects.
*When execution passes to callstringtt.p, the procedure creates an array of 64 handles and stores the values of the handles passed into the array so that temp-table copying is done only when required to invoke the call.
*If the mode of the parameter is OUTPUT or INPUT-OUTPUT and a property that was set using setPropertyList is specified, the value of the property is set on the server side. It is not synchronized with the client unless the entire call is executed on the client side.
calltable.p procedure
External procedure that allows for a single RUN statement to invoke a call using a temp-table that defines the parameter values. The temp-table can be in any of the formats supported by the include file. If a temp-table of type 1 or 2 is used, the parameters to the called object are not type checked. If a temp-table of type 3 or 4 is used, the call must be to a function or an internal procedure in a persistent procedure, and the signature is checked against the internal entries before the call is made. All outputs and return values from the invoked procedure are available through the appropriate rows on the returned temp-table.
Parameters:  
pcCallName INPUT CHARACTER
The name of an external or internal procedure or function to invoke.
pcTarget INPUT CHARACTER
Name of a manager procedure, the filename of a relatively or absolutely pathed procedure, or an integer value that evaluates to a procedure handle. If the value of this parameter is "" or the Unknown value (?), by default, pcCallName contains the name of a procedure that is to run nonpersistently.
The parameter is optional. If nothing is specified, then "" or the Unknown value (?) is passed.
pcTargetFlags INPUT CHARACTER
This parameter can contain modifiers that are used to invoke the persistent procedure. A modifier can be a valid combination of the following:
*P(ersistent) — Indicates that a new instance of the procedure should be instantiated persistently and left running.
*A(DM2) — Indicates that a new instance of an ADM2 procedure should be invoked persistently and the initializeObject internal procedure called to initialize it. The ADM2 procedure is left running after the call is complete.
*S(ingle) — Indicates that a new instance of the procedure should be instantiated if a running version is not found and left running.
*K(ill) — Indicates that if a procedure was instantiated during the call, it should be deleted before control is returned.
The default is to apply the behavior of the S parameter. That is, a persistent procedure is started if it is not found by walking the procedure stack and it is left running after the call is complete.
You can specify any of the P, A, or S modifiers in combination with K to shut down the procedure. For example, PK instructs the caller to instantiate a new instance of the procedure persistently and delete it when it is complete.
This parameter is optional. If nothing is specified, then "" is passed.
phCallParmTT INPUT HANDLE
Handle to a temp-table that could be either of the temp-tables defined in or a temp-table that was previously created by a call to one of the setupTTFrom functions. The output values from the call are written back into this table after the call has been invoked. If this parameter is not specified and there are parameters to the procedure or function, the parameters have to be specified in the phCallParmTH parameter.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
phCallParmTH INPUT-OUTPUT TABLE-HANDLE
Similar to phCallParmTT except that a TABLE-HANDLE is passed to support AppServer calls. The table is passed as an INPUT-OUTPUT parameter so that the return values can be returned to the client.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
Notes:  
*Once the procedure finishes executing, all temporary handles are deleted and the ttCall record no longer exists for the call. As a result, the Dynamic Call Wrapper has no information about this call so that there are no memory leaks created by calling callstring.p.
*The caller is responsible for cleaning up phCallParmTT and phCallParmTH.
*If phCallParmTT is specified, it is used to determine the parameters to the call. Otherwise phCallParmTH is used. If neither are specified the call is attempted with no parameters.
calltablett.p procedure
External procedure that allows a single RUN statement to invoke a call using a temp-table that defines the parameter values. The temp-table can be in any of the formats supported by the include file. If a temp-table of type 1 or 2 is used, the parameters to the called object are not type checked. If a temp-table of type 3 or 4 is used, the call has to be to a function or an internal procedure in a persistent procedure, and the signature is checked against the internal entries before the call is made. This variation of adm2/calltable.p supports the passing in of up to 64 temp-tables. For additional information, see the “callstringtt.p” section, the “calltable.p” section, and the “calltables.i” section.
All outputs and return values from the invoked procedure are available through the rows in the returned temp-table.
Parameters:  
pcCallNam INPUT CHARACTER
Name of an external or internal procedure or function to be invoked.
pcTarget INPUT CHARACTER
Name of a manager procedure, the filename of a relatively or absolutely pathed procedure, or an integer value that evaluates to a procedure handle. If the value of this parameter is "" or the Unknown value (?), by default, pcCallName contains the name of a procedure that is to be run nonpersistently.
This parameter is optional. If nothing is specified, then "" or the Unknown value (?) is passed.
pcTargetFlags INPUT CHARACTER
This parameter can contain modifiers that are used to invoke the persistent procedure. A modifier can be a valid combination of the following:
*P(ersistent) — Indicates that a new instance of the procedure should be instantiated persistently and left running.
*A(DM2) — Indicates that a new instance of an ADM2 procedure should be invoked persistently and the initializeObject internal procedure called to initialize it. The ADM2 procedure is left running after the call is complete.
*S(ingle) — Indicates that a new instance of the procedure should be instantiated if a running version is not found and left running.
*K(ill) — Indicates that if a procedure was instantiated during the call, it should be deleted before control is returned.
The default is to apply the behavior of the S parameter. That is, a persistent procedure is started if it is not found by walking the procedure stack and it is left running after the call is complete.
You can specify any of the P, A, or S modifiers in combination with K to shut down the procedure. For example, PK instructs the caller to instantiate a new instance of the procedure persistently and delete it when it is complete.
This parameter is optional. If nothing is specified, then "" is passed.
pcHandlesToSkip INPUT CHARACTER
By default the call wrapper runs DELETE OBJECT on tables that are listed in phCallTableHandle01 through 64 before returning. This avoids memory leaks caused by the duplication of temp-tables. In some cases this behavior might be undesirable, such as when the table being returned is a Progress Dynamics temp-table that should be retained in the cache on the server.
To address this issue, this parameter allows a comma- separated list of numbers between 1 and 64 corresponding to the handles below. If a number is found in the list, the corresponding handle is not deleted in the procedure prior to returning control to the caller.
Note: Using an * in a CAN-DO list indicates that none of the handles should be deleted.
This parameter is optional. If nothing is specified, then "" is passed.
phCallParmTT INPUT HANDLE
Handle to a temp-table that could be either of the temp-tables defined in a or a temp-table that was previously created by a call to one of the setupTTFrom functions. The output values from the call are written back into this table after the call has been invoked. If this parameter is not specified and there are parameters to the procedure or function, the parameters have to be specified in the phCallParmTH parameter.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
phCallParmTH INPUT-OUTPUT TABLE-HANDLE
Similar to phCallParmTT except that a TABLE-HANDLE is passed to support AppServer calls. The table is passed as an INPUT-OUTPUT parameter so that the return values can be returned to the client.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
phCallTableHandle01 to phCallTableHandle64 INPUT-OUTPUTTABLE-HANDLE
Table-handle that needs to be passed into the call.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
Notes:  
*Once the procedure has finished executing, all temporary handles are deleted and the ttCall record no longer exists for the call. As a result, the Progress Dynamics Call Wrapper has no information about this call so that there are no memory leaks created by calling callstring.p.
*The caller is responsible for cleaning up phCallParmTT, phCallParmTH, and the phCallTempTable or phCallTableHandle objects.
*When the execution passes to callstringtt.p, the procedure creates an array of 64 handles and stores the values of the handles passed into the array. As a result, a temp-table is copied only when required to invoke the call.
*If phCallParmTT is specified, it is used to determine the parameters to the call. Otherwise phCallParmTH is used. If neither are specified, the call is attempted with no parameters.
cleanupCall procedure
Procedure used to delete any objects associated with a call that might be left inside the Progress Dynamics Call Wrapper after the call finishes executing.
Parameters:  
piCall INPUT INTEGER
A call number returned from a previous invokeCall request. This call number identifies the call you want cleaned up.
pcHandles INPUT CHARACTER
A comma-separated CAN-DO list used to indicate which handles to clean up. You can specify:
*A — Asynchronous request handle.
*T — Progress Dynamics temp-table associated with call.
*H — Call Handle.
This parameter is optional. If nothing is specified, then "" is passed.
Notes:  
*By default, all three handles are deleted when cleanupCall is invoked. To have all handles except the Call Handle deleted, pass "!H".
*By default, the function appends an "*" to the end of the string so that all handles other than those explicitly specified are cleaned up.
determineTableType function
Function used to determine what type of table is contained in the handle passed as an input parameter.
Parameters:  
phBuffer INPUT HANDLE
Handle to either a temp-table object or a buffer object that contains the parameter values that you want to set.
Returns:  
The return values are:
*99 — Identifies a table that was previously formatted using one of the setupTTFrom functions.
*0 — Identifies a table that has no records in it. The 0 return value is also provided to indicate that there is no need to format the table using a setupTTFrom call.
*An integer value corresponding to one of the table types. This value can be:
*1 — Stores parameters by position using the native data type
*2 — Stores parameters by position using a character fields
*3 — Stores parameters by name using native data type
*4 — Stores parameters by name using a character field
Note: For more information, see the “calltables.i” section.
*Unknown value (?) — If the table type is not recognized.
InvokeCall procedure
Procedure used to invoke a call.
Parameters:  
pcProc INPUT CHARACTER
Name of the external or internal procedure, or function to be invoked.
phInHandle INPUT HANDLE
If pcProc is an internal procedure or function, this is the handle to the running persistent procedure that contains pcProc.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
piType INPUT INTEGER
Type of call being invoked. Must be either PROCEDURE-CALL-TYPE or FUNCTION-CALL-TYPE. These are constants that are recognized by the ABL Virtual Machine (AVM).
phParamTable INPUT HANDLE
Handle to a temp-table previously created by a call to one of the setupTTFrom functions.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
plPersistent INPUT LOGICAL
Indicates whether the external procedure specified in pcProc should be invoked persistently.
phServer INPUT HANDLE
Handle to the AppServer where the call is to run.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
plAsynch INPUT LOGICAL
If set to Yes, the call is invoked asynchronously.
pcEventProc INPUT CHARACTER
Applies only if plAsynch is set to Yes. This parameter identifies the procedure to be invoked when the asynchronous call completes.
This parameter is optional. If nothing is specified, then "" is passed.
phEventProcCtxte INPUT HANDLE
Contains the handle of the procedure that contains pcEventProc.
This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
piCal OUTPUT INTEGER
Unique identifier to the ttCall record that is created for this call. You can use this call number until cleanupCall is run to call either obtainCallInfo or cleanupCall.
Notes:  
*By default, all three handles are deleted when cleanupCall is invoked. To have all handles except the Call Handle deleted, pass "!H".
*By default, the function appends an "*" to the end of the string. As a result, all handles other than those explicitly specified are cleaned up.
obtainCallInfo function
Function used to obtain all the information about a call.
Parameters:  
piCall INPUT INTEGER
A call number returned from a previous invokeCall request. This call number identifies the call you want to obtain.
PcReturnValue OUTPUT CHARACTER
The return value from the invoked call.
PhParamTable OUTPUT HANDLE
Handle to the temp-table that contains the parameters to the call.
Returns: A handle to the DYNAMIC CALL object.
Note: If there is no call with the identifier specified, the unknown value the Unknown value (?) is returned.
obtainParamPropValue function
Function that obtains a property value or parameter value from the session.
Parameters:  
pcProperty INPUT CHARACTER
Name of a property whose value you want to obtain.
Returns: A character string containing the value of the property.
Note: The function first tries to evaluate the property by calling getPropertyList. If this fails, the function attempts to obtain the value of the property by calling getSessionParam.
obtainProcHandle function
Function that obtains the handle to a procedure that was previously instantiated.
Parameters:  
pcHandleName INPUT CHARACTER
Name of a handle to evaluate. The name can be one of the following:
*Name of a manager. If this is the case, getManagerHandle is called to determine the handle.
*Name of one of the predefined global variables that contain manager handles.
*Name of a procedure that could be running in the session.
Returns: A handle to the persistent procedure.
Note: If the filename option is used and the filename is not found in the persistent procedure list, the unknown value the Unknown value (?) is returned and the procedure is not instantiated.
setupTTFromSig function
Function used to create a dynamic temp-table that invokes a call from the signature of a procedure or function.
Parameters:  
pcTableName INPUT CHARACTER
Name to assign to the newly created temp-table.
phPersProc INPUT HANDLE
Handle to the persistent procedure that contains the call needed to derive the signature. This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
pcIntEntry INPUTCHARACTER
Procedure used to derive the signature for which a temp-table structure is to be created. This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
pcSignature INPUT CHARACTER
Signature of the procedure or function to invoke. This parameter is optional. If nothing is specified, then "" or the Unknown value (?) is passed.
phInitValueTT INPUT HANDLE
Handle to a temp-table that contains the parameter values to use for the call. This parameter is optional. If nothing is specified, then the Unknown value (?) is passed.
Returns: A handle to the created temp-table.
Notes:  
*You can specify phPersProc and pcIntEntry together, or you can specify pcSignature. If you specify all three, the contents of pcSignature is used.
*If you do not specify phInitValueTT, the values of the parameters are the default value for the data type of the parameter.
*The temp-table is created with initial values derived from the property values. No records are added to the temp-table. Creating a record in the table results in a record with the default values specified.
setupTTFromString function
Function used to create a Progress Dynamics temp-table to invoke a call from a string containing the parameter definitions in the form mode data type parameter.
Parameters:  
pcTableName INPUT CHARACTER
Name to assign the temp-table that you want to create.
pcRetValDT INPUTCHARACTER
Data type of the return value from the call. If left blank, the default is CHARACTER. This parameter is optional. If nothing is specified, the "" is passed.
pcParamString INPUT CHARACTER
A string in the form mode data type parameter, mode data type parameter. The string contains the parameters you want to pass to the procedure or function that is being invoked. The string is a comma-separated list of parameters. Each parameter is in the form "mode data type parameter" where:
*mode is one of INPUT, OUTPUT, INPUT-OUTPUT, or OUTPUT-APPEND.
*data type is one of CHARACTER, DATE, LOGICAL, INTEGER, DECIMAL, RAW, HANDLE, TABLE-HANDLE, or ROWID.
*parameter is the name of either a property that was previously set using setPropertyList or setSessionParam, or a single quoted constant that does not contain spaces or commas. If you specify a property, the procedure attempts to evaluate the property value by calling getPropertyList. If no property is available, or Progress Dynamics is not running, a call is made to getSessionParam for the property value. If neither call succeeds, the unknown value is passed.
Returns: A handle to the created temp-table.
Notes:  
*When the temp-table is constructed, the function attempts to find a property using getPropertyList with the same name as the parameter. If none is found, a similar attempt is made to call getSessionParam. If no properties or parameters are found in context, the initial value is set to the unknown value.
*The temp-table is created with initial values that are derived from the property values. No records are added to the temp-table. A create of a record in the table results in a record with the default values specified.
setupTTFromTable function
Function used to create a Progress Dynamics temp-table to invoke a call.
Parameters:  
pcTableName INPUT CHARACTER
Name to assign the temp-table you want to create.
pcRetValDT INPUT CHARACTER
Data type of the return value from the call. If left blank, the default is CHARACTER. This parameter is optional. If nothing is specified, then "" is passed.
phParamTable INPUT HANDLE
Handle to a table that has the structure of either of the temp-tables in the in calltables.i file located in the adm2/ directory.
Returns: Handle to the created temp-table.
Note: The temp-table is created with initial values derived from the records in the input table. No records are added to the temp-table. A create of a record in the table results in a record with the default values specified.