Under Language Environment®, you can specify service routines when executing
a main routine or subroutine in the preinitialized environment. To
use the routines, specify a list of addresses of the routines in a
service routine vector as shown in Figure 1.
Figure 1. Service routines
The service routine vector is composed of a list of doubleword
addresses of 64-bit XPLINK function pointers for routines that are
used instead of Language
Environment service routines. The list of addresses is preceded
by the number of doubleword addresses in the list, as specified in
the count field of the vector. The service_rtns parameter
that you specify in calls to CELQPIPI(init_main) and CELQPIPI(init_sub) contains
the address of the vector itself. If the pointer is specified as zero
(0), Language Environment routines
are used instead of the service routines that are shown in Figure 2.
The service routines must be 64-bit XPLINK functions. The function
descriptors pointed to by the service vector are standard 64-bit function
descriptors.
Figure 2. 64-bit function
descriptors
When the service routine is called, Register 5 will contain the
first 8 bytes in the function descriptor. The service routine will
be called at the entry point address contained in the second 8 bytes
of the function descriptor. Register 7 will be the return address
to Language Environment.
Register 4 will point to the caller's DSA, and the service routine
can obtain a 64-bit XPLINK DSA using the usual methods.
In most cases, Register 4 points into the normal 64-bit XPLINK
stack for the current TCB. In a few cases, Register 4 might point
to some other fixed-size 64-bit stack, or to the regular 64-bit Language Environment stack
for a different TCB. In these cases, there will be at least 4K of
free space in the nonstandard stack to obtain a new XPLINK DSA.
The first three XPLINK parameters are passed in Registers 1, 2,
and 3. Parameters 4 through 'n' are available in the caller's XPLINK
argument area, starting 0x898 bytes past the input Register 4. The
service routine can save the first three parameters (in registers
1, 2, and 3) in the caller's argument area starting at offset 0x880,
if required.
These XPLINK function descriptions must remain accessible at the
specified address from the time of the first CELQPIPI initialization
call until the final CELQPIPI termination call has returned.
The @GETSTORE and @FREESTORE service routines must be specified
together; if one is zero, the call to CELQPIPI(init_main) or CELQPIPI(init_sub)
fails. The same is true for the @LOAD and @DELETE service routines.
If you specify the @GETSTORE and @FREESTORE service routines, you
do not have to specify the @LOAD and @DELETE service routines, and
vice versa.
When replacing only the storage management routines without the
program management routines, the user must be aware that they may
not be accounting for all of the storage obtained on behalf of the
application. Contents management obtains storage for the load module
being loaded. This storage will not be managed by the user storage
management routines.
- 00000000
- A fullword zero at the start of the service routine vector.
- Count
- A fullword binary number representing the number of doublewords
that follow. The count does not include itself. If the count does
include any of the reserved doublewords, those doublewords must be
set to zero.
- User Word
- A doubleword that is passed to the service routines. The user
word is provided as a means for your routine to communicate to the
service routines.
- @LOAD
- This routine loads named routines for application management.
The parameters that are passed contain the following:
- Name_addr
- The 64-bit address of the name of the module to load (input parameter).
- User_word
- A doubleword user field (input parameter).
- Load_point
- Either zero (0), or the 64-bit address where the @LOAD routine
is to store the load point address of the loaded routine (input and
output parameter). If not zero, it points to an 8-byte area. The 64-bit
address of the load point is to be saved in this output area.
- Entry_point
- The 64-bit entry point address of the loaded routine (output parameter).
- Module_size
- The fixed binary(31) size of the module that was loaded (output
parameter).
- Return_code
- The fullword return code from load (output).
- Reason_code
- The fullword reason code from load (output).
The following table lists the return and reason
codes. AA should be the Abend (low 16 bits) code from the LOAD MACRO,
and RR can be the reason code (low 16 bits) from the LOAD MACRO:
| Return code |
Reason code |
Description |
|---|
| 0 |
0 |
Successful |
| 0 |
3 |
Successful - loaded using SVC8 |
| 8 |
AARR |
Unsuccessful - module not found |
| 12 |
AARR |
Unsuccessful - not enough storage |
| 16 |
AARR |
Unsuccessful |
| 20 |
AARR |
Unsuccessful - module came from unauthorized
library (abend code 306 from LOAD) |
- @DELETE
- This routine deletes routines for application management. The
parameters that are passed contain the following:
- Name_addr
- The 64-bit address of the module name to be deleted (input parameter).
- Name_length
- A fixed binary(31) length of module name (input parameter).
- User_word
- A doubleword user field (input parameter).
- Rsvd_word
- A fullword reserved for future use. Any value that might be present
in this parameter should not be relied upon.
- Return_code
- The fullword return code from the delete service (output parameter).
- Reason_code
- The fullword reason code from the delete service (output parameter).
The following table lists the return and reason
codes.
| Return code |
Reason code |
Description |
|---|
| 0 |
0 |
Successful |
| 4 |
4 |
Unsuccessful - DELETE failed |
- @GETSTORE
- This routine allocates storage on behalf of the Language Environment storage
manager. Three types of storage can be requested: below the 16MB line,
below the 2GB bar, and above the 2GB bar. The parameter list that
is passed contains the following:
- PISA_Addr
- A doubleword address of the PreInit storage attributes (PISA)
control block (input parameter). This control block, defined in macro
CELQPIDF, contains the attributes that the GETSTORE routine is to
use when obtaining the storage. Table 1 shows
the control block field descriptions.
Table 1. PreInit storage attributes control block field descriptions| Name |
Description |
|---|
| PisaVersion |
A fullword field that contains the version number
of this PISA. The only valid value for this field is currently 1,
but other values may be added in the future when new storage attributes
are added to this interface. The GETSTORE service routine should check
this field to verify that it supports the specified version; if it
cannot support the version, it should return with a return code of
8. |
| PisaAmount |
An unsigned doubleword that contains the amount
of storage requested. For below-the-bar storage, the amount of storage
to obtain is in the number of bytes. For above-the-bar storage, the
size of the memory object to obtain is in the number of megabytes. Note: Above-the-bar
storage that is returned by @GETSTORE must be aligned on a 1 MB boundary.
|
| PisaFlags |
A doubleword flag area. The flags are defined
as follows: - PisaBelowtheLine
- Bit zero in PisaFlags is ON if the requested storage is required
to be below the 16 MB line.
- PisaBelowtheBar
- Bit one in PisaFlags is ON if the requested storage is required
to be below the 2 GB bar.
- PisaAbovetheBar
- Bit two in PisaFlags is ON if the requested storage is required
to be above the 2 GB bar.
- PisaGuardLoc
- Bit three in PisaFlags specifies whether the guard location is
at the low virtual end or the high virtual end of the memory object.
Bit three is OFF if the guard areas are created starting from the
origin of the memory object; that is, from the low virtual end. Bit
three is ON if the guard areas are created at the end of the memory
object, that is, at the high virtual end. This flag is used for above-the-bar
storage only, and only has meaning when PisaGuardSize is nonzero.
Failure to guard the memory object as requested may cause Language
Environment's stack management features to work incorrectly.
- PisaPageFrameSize1MEG
- Bit four in PisaFlags is ON if the memory object is to be backed
by 1-megabyte page frames (equivalent to IARV64 PageFrameSize=1MEG).
When both bits four and five are off, the memory object is backed
by 4 KB page frames (equivalent to IARV64 PageFrameSize=4K). This
flag is used for above-the-bar storage only. Failure to provide storage
with this attribute might have a performance impact in your application.
- PisaPageFrameSizeMAX
- Bit five in PisaFlags is ON if the memory object is to be backed
by the largest page frame size supported (equivalent to IARV64 PageFrameSize=MAX).
When both bits four and five are off, the memory object is backed
by 4 KB page frames (equivalent to IARV64 PageFrameSize=4K). This
flag is used for above-the-bar storage only. Failure to provide storage
with this attribute might have a performance impact in your application.
|
| PisaSubpool_no |
A fixed binary(31) subpool number from 0 to
127. Language Environment allocates
storage from the process-level storage pools. This field is used for
below-the-bar storage only. |
| PisaDumpPriority |
A fullword dump priority for memory objects.
This field is used for above-the-bar storage only. Failure to provide
storage with the requested dump priority may result in a dump that
does not contain useful diagnostic information. |
| PisaGuardSize |
A doubleword indicating the number of megabytes
of guard area to be created at the high or low end of the memory object.
This field is used for above-the-bar storage only. Failure to guard
the memory object as requested might cause Language Environment's
stack management features to work incorrectly. |
| PisaUsertkn |
A doubleword token to be associated with a group
of memory objects. This can be used on a later FREESTORE request to
free all memory objects that are associated with this value. This
field is used for above-the-bar storage only. Note: Non-authorized
callers cannot directly use the UserTkn provided by Language Environment because Language Environment uses
the authorized word in the high half. Refer to the sample @GETSTORE
routine to see one way of handling this.
|
- User_word
- A doubleword field containing the user word supplied in the Service
Routine Vector (input parameter).
- Stg_address
- A doubleword address of the storage obtained or zero (output parameter)
.
- Obtained
- An unsigned doubleword that contains the number of bytes (below
the bar) or megabytes (above the bar) obtained (output parameter).
Note: Storage
must be obtained in a key that is compatible with the application.
- Return code
- The fullword return code from the @GETSTORE service (output parameter).
- Reason code
- The fullword reason code from the @GETSTORE service (output parameter).
The following table lists the return and reason
codes:
| Return code |
Reason code |
Description |
|---|
| 0 |
0 |
Successful |
| 8 |
0 |
The specified version of the PISA is not supported
by this service routine. |
| 16 |
0 |
Unsuccessful - uncorrectable error occurred. |
- @FREESTORE
- This routine frees storage on behalf of the Language Environment storage
manager. The parameter list that is passed contains the following:
- Stg_address
- The doubleword address of the storage or memory object to free
(input parameter) .
Note: Stg_address is zero when MatchUsertkn is
ON.
- Amount
- An unsigned doubleword that contains the amount of storage in
bytes to free (input parameter). This field is used for below-the-bar
storage only.
- Subpool_no
- The fixed binary(31) subpool number from 0 to 127 (input parameter).
This parameter is used for below-the-bar storage only.
- Flags
- A doubleword flag area (input parameter), defined as follows:
- MatchUsertkn
- Bit zero in Flags indicates how the value specified in parameter
UserTkn is to be used. If MatchUsertkn is ON, the @FREESTORE routine
is expected to free all memory objects that are associated with this
user token (equivalent to IARV64 MATCH=USERTKN). If MatchUsertkn is
OFF, @FREESTORE is to use this user token when freeing a single memory
object with the origin in Stg_address (equivalent to MATCH=SINGLE).
This flag is used for above-the-bar storage only.
- UserTkn
- A doubleword token that identifies the memory object or a group
of memory objects to be detached (input parameter). This parameter
is used for above-the-bar storage only.
- User word
- A doubleword field containing the user word supplied in the Service
Routine Vector (input parameter).
- Return code
- The fullword return code from the @FREESTORE service (output parameter)
.
- Reason code
- The fullword reason code from the @FREESTORE service (output parameter).
The following table lists the return and reason
codes.
| Return code |
Reason code |
Description |
|---|
| 0 |
0 |
Successful |
| 16 |
0 |
Unsuccessful - uncorrectable error occurred. |
- @MSGRTN
- This routine allows error messages to be processed by the caller
of the application.
If the message pointer is zero, your message
routine is expected to return the size of the line to which messages
are written (in the line_length field). This allows messages to be
formatted correctly; that is, broken at places such as blanks.
- Message
- A pointer to the first byte of text that is printed, or zero (input
parameter).
- Msg_len
- The fixed binary(31) length of the message (input parameter).
- User word
- A doubleword user field (input parameter).
- Line_length
- The fixed binary(31) size of the output line length (output parameter).
This is used when Message is zero.
- Return code
- The fullword return code from the @MSGRTN service (output parameter).
- Reason code
- The fullword reason code from the @MSGRTN service (output parameter).
The following table lists the return and reason
codes.
| Return code |
Reason code |
Description |
|---|
| 0 |
0 |
Successful |
| 16 |
4 |
Unsuccessful - uncorrectable error occurred. |
z/OS Language Environment Programming Guide for 64-bit Virtual Addressing Mode
Copyright IBM Corporation 1990, 2014