Previous Topic Next topic Print topic


CBL_GET_PROGRAM_INFO

Returns information for a named program, or a program in the current call stack.
Restriction: Function 8 of this routine (return number of arguments) is supported for native COBOL only.

Syntax:

call "CBL_GET_PROGRAM_INFO" using by value function
                            by reference   param-block
                            by reference   return-buf
                            by reference   return-buf-len
                            returning      status-code

Parameters

function
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
param-block
Group predefined as cblt-prog-info-params containing
 01 cblt-prog-info-params   typedef.
   03 cblte-gpi-size        cblt-x4-comp5.   *> pic x(4) comp-5.
   03 cblte-gpi-flags       cblt-x4-comp5.   *> pic x(4) comp-5.2.
   03 cblte-gpi-handle      cblt-pointer.    *> usage pointer.
   03 cblte-gpi-prog-id     cblt-pointer.    *> usage pointer.
   03 cblte-gpi-attrs       cblt-x4-comp5.   *> pic x(4) comp-5.
return-buf
Call prototype (see Key): cblt-prog-info-arg-info
Picture: pic x(n).
return-buf-len
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

function
Specifies the function to be performed:
0 Return status information for the current program. If you want to retrieve further information on this program, then bit 0 of the cblte-gpi-flags parameter must be set to indicate that this function should return cblte-gpi-handle, which will be used as an input to function 2 through 8. The initial program associated with cblte-gpi-handle is the current program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

1 Return status information for named program. If you want to retrieve further information on this program, then bit 0 of the cblte-gpi-flags parameter must be set to indicate that this function should return cblte-gpi-handle, which will be used as an input to function 2 through 8. The initial program associated with cblte-gpi-handle is the named program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

2 Return status information for the program that called the program currently associated with cblte-gpi-handle. This function requires that cblte-gpi-handle has been set up using functions 0 or 1. The program associated with cblte-gpi-handle is updated to the calling program.

When other functions that use cblte-gpi-handle have completed, you must use CBL_GET_PROGRAM_INFO again, with function set to 3, to deallocate the handle.

3 Close a previously created cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been created using function 0 or 1. A call with this function must be made when cblte-gpi-handle is finished with.
4 Find the first entry point of the program currently associated with cblte-gpi-handle. cblte-gpi-handle must have been set up using function 0 or 1. Once a call with this function has been made, you can repeatedly use this routine with function set to 5 to retrieve all remaining entry points in the program. Once all of the required entry points have been returned, you can use this routine with function set to 6 to terminate the entry-point search.
5 Find the next entry point of the program currently associated with cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been set up using function 0 or 1, and for function 4 to have been used to initiate the find first/next entry-point sequence.
6 Terminate the entry-point search. It requires a valid cblte-gpi-handle to have been set up using function 0 or 1, and for function 4 to have been called to initiate the find first/next entry-point sequence.
7 Return the full program-name of the program currently associated with cblte-gpi-handle. This function requires a valid cblte-gpi-handle to have been set up using function 0 or 1.
8 Return the number of arguments the program currently associated with cblte-gpi-handle was called with. This information can only be returned if the program is on the current call stack.
Restriction: Function 8 (return number of arguments) is supported for native COBOL only.
cblte-gpi-size
The size of the parameter block including this field. This should be set to a value of 20 on 32-bit systems, or 28 on 64-bit systems.
cblte-gpi-flags
A 32-bit word indicating what information is to be returned:
Bit 0
Determines whether functions 0 and 1 return cblte-gpi-handle. For all other functions, this bit is ignored.
0 Do not return cblte-gpi-handle (if function is set to 0 or 1)
1 Return cblte-gpi-handle (if function is set to 0 or 1)
Bit 1
Determines whether functions 0 and 2 should return the program's basename in name-buf as part of the program status information.
0 Do not return basename of program (if function is set to 0 or 2)
1 Return basename of program in name-buf (if function is set to 0 or 2)
Bit 2
Determines whether basenames and full program names that are input or returned in name-buf should be in null-terminated or space- terminated format.
0 All input and output names are space-terminated
1 All input and output names are null-terminated.
Bit 3
Determines whether functions 0, 1and 2 should return the program's attributes in cblte-gpi-attr.
0 Do not return program attributes in cblte-gpi-attr.
1 Return program attributes in cblte-gpi-attr.
Bits 4-31
Reserved for future use - must be set to 0.
cblte-gpi-handle
A handle created by function 0 or 1.
return-buf
If function is set to:
0 The basename of the program for which information is required.
8 A group predefined as
01 RETURN-BUF.
     05 cblte-gpiai-size        pic x(4) comp-5 value zeroes.
     05 cblte-gpiai-argc        pic x(4) comp-5 value zeroes.
     05 cblte-gpiai-reserved1   pointer value null.
     05 cblte-gpiai-reserved2   pointer value null.

cblte-gpiai-size must be set to either 16 on 32-bit systems or 24 on 64-bit systems.

return-buf-len
The length of return-buf. If this is too small for the information being returned, the routine fails.

On Exit:

cblte-gpi-handle
The handle returned by functions 0 and 1, which must be used for all other functions.
cblte-gpi-prog-id
Unique identifier for the program currently associated with cblte-gpi-handle.
cblte-gpi-attr
Attributes of the program currently associated with cblte-gpi-handle.
Bit 0
0 Program not compiled using AMODE"24" Compiler directive.
1 Program compiled using the AMODE"24" Compiler directive .
Bit 1
0 Program not compiled using AMODE"31" Compiler directive.
1 Program compiled using the AMODE"31" Compiler directive .
Bit 2
0 Program compiled using the CHARSET(ASCII) Compiler directive.
1 Program compiled using the CHARSET(EBCDIC) Compiler directive.
Bit 3
0 Program not compiled using the ANS85 Compiler directive.
1 Program compiled using the ANS85 Compiler directive.
Bit 4
0 Program not compiled using the VSC2 Compiler directive.
1 Program compiled using the VSC2 Compiler directive (this Compiler directive is supported in native code only).
Bit 5
0 Program not compiled using the OSVS Compiler directive.
1 Program compiled using the OSVS Compiler directive (this Compiler directive is supported in native code only).
Bits 6-25
Reserved for future use - must be set to 0.
Bit 26
0 Program is not a system program.
1 Program is a system program.
Bit 27
Reserved for future use - must be set to 0.
Bit 28
0 Program is not a member of a subsystem.
1 Program is a member of a subsystem.
Bit 29
0 Program exists in current call stack.
1 Program does not exist in current call stack.
Bit 30
0 Program is not canceled.
1 Program is canceled.
Bit 31
0 Program is COBOL.
1 Program is non-COBOL.
return-buf
If function was set to:
0, 2 The basename that was requested.
4, 5 The entry point name that was requested.
7 The full program name that was requested.
8 The call parameter information that was requested, where cblte-gpiai-argc contains the number of arguments the program was called with.

cblte-gpiai-reserved1 and cblte-gpiai-reserved2 remain set to NULL.

return-buf-len
Length of the name returned in name-buf, or required buffer length if the status-code is 1013.
status-code
Status of operation:
0 Success.
500 End of information (returned by function 2 when there is no caller of the currently associated program, or by function 5 when no more entry points exist).
1000 Memory allocation error.
1001 Invalid cblte-gpi-handle input.
1006 Invalid operation on handle (returned by function 8 if the program associated with cblte-gpi-handle is not on the call stack).
1009 Invalid parameter.
1011 Program or entry name not found.
1013 Buffer too small for information to be returned.
Previous Topic Next topic Print topic