Activate Bound Program Long (QleActBndPgmLong) API
Required Parameter:
| 1 | Pointer to bound program | Input | PTR(SYP) |
Omissible Parameter Group:
| 2 | Activation mark | Output | Binary(8) |
| 3 | Activation information | Output | Char(*) |
| 4 | Length of activation information | Input | Binary(4) |
| 5 | Error code | I/O | Char(*) |
Returned Value:
| Activation mark | Output | Binary(8) |
Default Public Authority: *USE
Service Program: QLEAWI
Threadsafe: Yes
The Activate Bound Program Long (QleActBndPgmLong) API activates the bound program or service program specified by the pointer to bound program parameter if it is not already active. All dependent service programs are activated, and all initialization of the newly activated service programs is done.
Initialization may consist of calling user procedures. All unhandled exceptions that occur during initialization will be percolated to the caller of QleActBndPgmLong; they will never be returned in the error code parameter. QleActBndPgmLong will never move the resume cursor for the exception. Therefore, it is possible for the caller of QleActBndPgmLong to handle an exception and resume initialization.
This API is identical to the Activate Bound Program (QleActBndPgm) API except that all mark values produced or consumed by the API are Binary(8) mark values. The QleActBndPgm API produces and consumes Binary(4) mark values. The QleActBndPgmLong API is normally used in conjunction with the Get Export Long (QleGetExpLong) API. First, you activate a service program using the QleActBndPgmLong API, and then later you use the QleGetExpLong API to retrieve pointers to procedures and data from that activation.
The QleActBndPgmLong API may not be called in a secondary thread of a Common Platform Architecture (CPA) application.
Authorities and Locks
None.
Required Parameter
- Pointer to bound program
- INPUT; PTR(SYP)
A system pointer to the program or service program to be activated.
Omissible Parameter Group
- Activation mark
- OUTPUT; BINARY(8)
The entity uniquely identifying the activation within the current job.
- Activation information
- OUTPUT; CHAR(*)
The structure that contains additional activation information. The format of this structure is shown in Format of Activation Information. If activation information is specified, the length of activation information parameter must also be specified. The storage for activation information must be on a 16-byte boundary.
- Length of activation information
- INPUT; BINARY(4)
The length of the activation information. If the length is larger than the size of the storage for activation information, the results may not be predictable. The minimum length is 8 bytes.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Returned Value
- Activation mark
- OUTPUT; BINARY(8)
This API returns the value for the activation mark parameter.
Format of Activation Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(8) | Reserved |
| 16 | 10 | BINARY(8) | Activation group mark |
| 24 | 18 | BINARY(8) | Activation mark |
| 32 | 20 | CHAR(7) | Reserved |
| 39 | 27 | CHAR(1) | Flags |
| 40 | 28 | CHAR(8) | Reserved |
Field Descriptions
Activation group mark. An entity uniquely identifying the activation group within the current job.
Activation mark. An entity uniquely identifying the activation within the current job.
| Flags | Bit values | ||||
|---|---|---|---|---|---|
| Bit 0 |
|
||||
| Bit 1-7 | Reserved |
Bytes available. The length of all available information that could be returned. Bytes available can be greater than the length of activation information parameter. If it is greater, the information returned is truncated to the length specified.
Bytes returned. The length of all information returned. The value of the bytes returned field is always less than or equal to the length returned in the bytes available field.
Reserved. An area of reserved storage.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| MCH3402 E | The argument being tested is not an address. |
| MCH4421 E | At least one field in the allocation strategy is not valid. |
| MCH4430 E | The exit priority value provided for &1 is not valid. |
API introduced: V5R3
[ Back to top | Program and CL Command APIs | APIs by category ]