Micro Focus Studio Enterprise Edition for Windows > General Reference > Library Routines > Alphabetical List of Library Routines > CBL_GET_PROGRAM_INFO

Micro Focus Studio Enterprise Edition for Windows > General Reference > Library Routines > Program Information Routines > CBL_GET_PROGRAM_INFO

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:

The basename of the program for which information is required.

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 (this Compiler directive is supported in native code only).

Bit 1

0	Program not compiled using AMODE"32" Compiler directive.
1	Program compiled using the AMODE(31) Compiler directive (this Compiler directive is supported in native code only).

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).

Bit 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 not 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.