This document describes functionality and operation of the Authorized Services Manager (ASM) which is available with Natural under z/OS.
The following topics are covered:
The Authorized Services Manager (ASM) provides authorized operating system functions to Natural. These functions include writing SMF records and z/OS Parallel Sysplex communication through the Coupling Facility (CF). The ASM provides its functions via PC routines and runs in its own address space.
The following authorized functions are provided:
communicating Natural buffer pool administration messages,
write-access to global buffer pools in system key,
writing SMF records,
holding Natural session information in the Session Information Pool (SIP).
The first three functions are always available, whereas the SIP is optional and can be made available via startup parameter. For more information on starting the ASM, see Starting the ASM.
You must use the ASM in the following cases:
The Natural profile parameter BPPROP
is set to
PLEX
or GLOBAL
or GPLEX
(buffer pool
propagation is used).
Natural global buffer pools are allocated in system key; see Installing the Natural GBP Operating Program.
Natural under CICS is used in a z/OS Parallel Sysplex (SIP function required).
Natural under IMS TM is used in terminal-oriented, non-conversational mode (with the SIP function).
Natural under IMS TM is used, with the Accounting function writing SMF records.
The Session Information Pool (SIP) holds the Natural session information records. In terminal-oriented non-conversational mode, the NCI and NII interfaces need these records to continue a Natural session after a terminal I/O. When running in a z/OS Parallel Sysplex environment, the SIP is created in the CF and a data space is used as an intermediate buffer to avoid unnecessary access to the CF. Otherwise, the SIP is created in a data space.
If the ASM is used in a z/OS Parallel Sysplex environment, one ASM instance must be started in each participating z/OS image.
Note concerning Natural/CICS: The CICS
System Recovery Table should include the z/OS system abend code
0D6
.
Link the modules NATASMvr
(vr=version,
release number) and NATBPMGR
to an
Authorized Program Facility (APF) library, specifying
IEWL
parameter AC(1)
. Refer to
Installation
Procedure for Natural under z/OS.
As the ASM reserves one system linkage index (System LX), check
whether there is a high enough value of NSYSLX
in member
IEASYSxx
of library
SYS1.PARMLIB
.
Note:
If you terminate the ASM, the address space ID is no longer
available because a System LX has been used. It becomes available again with
the next IPL.
A CF structure is only used if you run the SIP in a z/OS Parallel Sysplex environment. The space required can be calculated using the following formula:
30 KB + (SIP slot size in bytes + 165) * (number of SIP slots + 8)
For 500 SIP slots of 512 bytes each, define:
STRUCTURE NAME(NATASM) SIZE(380) PREFLIST(CF1)
To propagate buffer pool administration messages in a z/OS Parallel
Sysplex environment, the XCF Signalling Services are used. The minimum message
is 64 bytes long, the maximum is 2048 bytes. How often messages are sent
depends on how often Natural objects are manipulated (with the system command
CATALOG
, STOW
or
DELETE
).
The following is covered below:
You start the ASM either as a batch job or as a started task by
executing module NATASM
vr, where
vr stands for the current Natural version and
release number. On the JCL EXEC
statement, specify as
PARM
the following parameters:
subsystem-id,XCF-group-name,CF-structure-name,number-of-SIP-slots,SIP-slot-size,message-case
All parameters are positional and must be separated by a comma; they are explained in the table below:
Parameter | Possible Values | Default | Comment |
---|---|---|---|
subsystem-id
|
4-byte non-blank string | NATv
|
The specified value must match the value of the Natural profile
parameter Note: |
XCF-group-name
|
any valid XCF group name | none | The name of the XCF group for signalling services. |
CF-structure-name
|
any valid CF structure name | none | Optional, only needed if SIP is used. The name of the CF structure used for the SIP function. |
number-of-SIP-slots
|
1 - 32767 |
none | Optional, only needed if SIP is used. The number of slots to be
allocated if the CF structure has not yet been allocated. If omitted or
specified as 0 , the entire structure will be used for as many
slots as it can hold.
|
SIP-slot-size
|
256 , 512 , 1024 ,
2048 , 4096 |
1024 |
The specified value is ignored if a CF structure has already been allocated. |
message-case |
UCTRAN or blank
|
blank | Specify UCTRAN if the Authorized Services Manager
is to issue all its messages in upper case.
|
Examples:
//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF,CFSIP,1500,512'
The subsystem ID is NATv
, the
message group for buffer pool communication is NATXCF
, the
structure for the Session Information Pool is CFSIP. 1500 SIP slots are to be
used, each having a size of 512 bytes.
//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF,CFSIP'
Same as above, except SIP slots:
The ASM will use as many SIP slots as the CFSIP structure can hold, each having a size of 1024 bytes.
//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF,,500,512'
The SIP service is not to use the Coupling Facility, but to build 500 SIP slots in storage, each having a size of 512 bytes.
//ASM EXEC PGM=NATASMvr,PARM='NATv,NATXCF'
The SIP service will not be available.
The ASM writes informational and error messages to
JESMSGLG
using the WTO
macro
(ROUTCDE=11
). The messages are preceded by a message identifier
and the ASM's job name, for example:
ASM0005 FBASMvr
In this example, Authorized Services Manager Version vrs (vr=version, release, system maintenance level) is active
The following condition codes are used:
Condition Code | Explanation |
---|---|
0
|
Normal completion |
12
|
Wrong parameter input |
16
|
Runtime error has occurred |
20
|
Subtask has failed |
24
|
Abend has occurred |
>100
|
Working storage could not be allocated |
The following user abend codes are used:
Abend Code | Reason | Comment |
---|---|---|
U0100
|
IXCJOIN failed.
|
Abend Register 14 contains the reason code. |
U0101
|
IXCQUERY failed.
|
Abend Register 14 contains the reason code. |
U0103
|
Active member list full. | Contact Software AG Support. |
U0104
|
IXCMSGI failed.
|
Abend Register 14 contains the reason code. |
U0105
|
Message Exit could not obtain a Purge Task Request Block. | Contact Software AG Support. |
U0106
|
Work Space for IXLCONN could not be
obtained.
|
Contact Software AG Support. |
U02xx |
DSPSERV CREATE failed.
|
xx is the reason code. |
U03xx
|
ALESERV ADD failed.
|
xx is the reason code. |
U04xx
|
ALESERV ADD failed.
|
xx is the reason code. |
U05xx
|
IXLCONN failed.
|
xx is the reason code. |
U06xx
|
IXLLIST WRITE failed.
|
xx is the reason code. |
To find a description of reason codes, refer to Programming: Sysplex Services Reference (IBM documentation). If the error was environment-specific, and it is not clear what the reason was, contact Software AG Support.
The following commands can be passed to the ASM using the
MODIFY
command:
Command | Description |
---|---|
TERM
|
Terminates the ASM. |
TRSTART
|
Debugging function, only to be used at Software AG's advice. Activates the Trace Task. If the GTF is started and enabled for User Records 202, the trace records are written to the GTF. |
TRSTOP
|
Deactivates the Trace Task. |
SNAP
|
Debugging function. The ASM's address space is dumped to
SYSUDUMP .
|
VLIST |
Display name, version, and assembly time of modules that are linked to the ASM. |
For a list of return codes and reason codes of the SIP Service, refer to SIP Service Return Codes and Reason Codes in the Messages and Codes documentation.