This general macro provides addressability to an SSU slot in the Subsystem
User Table (MS0UT) for both C-type and E-type programs. The macro
determines the requested SSU slot address and places it in a user-specified
register so that upon return, the user can access the data in the SSUT via the
MS0UT macro.
Format
- label
- A symbolic name can be assigned to the macro statement.
- IDLOC
- This is a required parameter that specifies the location of the SS/SSU ID
to be used as input to the UATBC macro. Upon return, the general
register specified by 'Rx' will contain the SSUT slot address of the
specified SSU, adjusted for the SSUT header.
The valid request types are listed below.
- (E,SSI,Rx)
- This specifies that the input SS ID is supplied in the ECB field
CE1DBI.
- (E,SSU,Rx)
- This specifies that the input SSU ID is supplied in the ECB field
CE1SSU.
- (R,SSI,Rx)
- This specifies that the input SS ordinal number is supplied in the
rightmost byte of 'Rx'. The high-order 3 bytes of 'Rx'
are irrelevant.
- (R,SSU,Rx)
- This specifies that the input SSU ordinal number is supplied in the
rightmost byte of 'Rx'. The high-order 3 bytes of 'Rx'
are irrelevant.
- (N,SSI,Rx)
- This specifies that the input SS name is supplied in 'Rx'.
The SS name must be a maximum of 4 characters, left justified, and padded with
blanks on the right.
- (N,SSU,Rx)
- This specifies that the input SSU name is supplied in 'Rx'.
The SSU name must be a maximum of 4 characters, left justified, and padded
with blanks on the right.
- EXCD=address
- This is the address of a user exit routine to which control will be passed
if the 'exceeded' condition is raised. This parameter is
optional, but if omitted and the condition is raised, a system error is
taken. This parameter is invalid if used with
IDLOC=(N...).
- INVLID=address
- This is the address of a user exit routine to which control will be passed
if the 'invalid' condition is raised. This parameter is
optional, but if omitted and the condition is raised, a system error is
taken. This parameter is ignored when
IDLOC=(R...).
- NOTAVL=address
- This is the address of a user exit routine to which control will be passed
if the 'not available' condition is raised. This parameter is
optional, but if omitted and the condition is raised, a system error is
taken.
- NAME=Ry
- This is the general register that is to contain the SS name, left
justified, upon return. This SS is the parent SS of the SSU whose
adjusted slot address is being returned by the UATBC macro. This
parameter is optional.
- COUNT=Rz
- This is the general register that is to contain a number of SSUs upon
return. If IDLOC=(x,SSI,x) is coded, this number is the total number of
SSUs in the specified SS. If IDLOC=(x,SSU,x) is coded, this number is
the number of SSUs remaining in the parent SS of the specified SSU, including
the specified SSU itself. This parameter is optional.
Entry Requirements
- If called by an E-type program, then R9 must contain the address of the
ECB being processed.
- If called by a C-type program and IDLOC=(E,x,x) is specified, then R9 must
contain the address of the ECB being processed.
- The location of the input to this macro is specified on the IDLOC
parameter.
Return Conditions
- Control is returned to the next sequential instruction.
- For E-TYPE programs the contents of R14 and R15 are unknown.
- For C-TYPE programs the contents of R14 are unknown.
- The contents of all other registers, excluding those specified in the
macro parameters, are preserved across this macro call.
- The register specified in the IDLOC parameter contains the adjusted SSU
slot address of an SSU within MS0UT.
- If IDLOC=(x,SSI,x) is coded, the adjusted slot address of the first SSU
within the specified SS is returned.
- If IDLOC=(x,SSU,x) is coded, the adjusted slot address of the specified
SSU is returned.
- The MS0UT DSECT tags should be used to reference the SSU slot returned,
since there is no guarantee that the SSUT format will be unchanged in the
future.
- If the NAME option is specified, the name of the parent SS of the SSU
whose adjusted slot address is being returned by this macro is returned in the
specified register, left justified, and padded with blanks on the
right. The NAME option supersedes the IDLOC parameter. That is,
if the same register is specified in both the IDLOC and NAME parameters, the
contents of the register upon return will be a NAME, not an SSUT slot
address.
- If the COUNT option is specified, a count is returned in the specified
register.
- If IDLOC=(x,SSI,x) is coded, this count is the total number of SSUs in the
specified SS.
- If IDLOC=(x,SSU,x) is coded, this count is the number of SSUs remaining in
the parent SS of the specified SSU, including the specified SSU itself.
The COUNT option supersedes the NAME and IDLOC parameters. That is,
if the same register is specified for the COUNT option as is specified for
either the NAME or IDLOC parameters, the contents of the register upon return
from the macro will be a count, not a NAME or an SSUT slot address.
- If an 'EXCD', 'INVLID', or 'NOTAVL' error
condition is encountered while servicing a UATBC macro call, a branch is taken
to the corresponding user exit label specified on the macro call, if
provided. If one of these conditions is raised for which no user exit
is provided, a system error is taken.
- For E-type programs, the ECB is exited.
- For C-type programs, the error is catastrophic.
The following table summarizes the circumstances that can raise the user
error conditions:
IDLOC
| EXCD
| INVLID
| NOTAVL
|
E
| SSI
| EI
| I1
| 01
|
E
| SSU
| EI
| I1
| 02
|
R
| SSI
| E2
| N/A
| 01
|
R
| SSU
| E2
| N/A
| 02
|
N
| SSI
| N/A
| I3
| 01
|
N
| SSU
| N/A
| I3
| 02
|
- E1
- CE1DBI or CE1SSU complies with the identification integrity; that is,
ordinal number plus complement is equal to X'FF'. However, the
SS or SSU ordinal number exceeds the number of SSs/SSUs included in the last
IPL.
- E2
- The SS or SSU ordinal number supplied in 'Rx' exceeds the number
of SSs/SSUs included in the last IPL.
- N/A
- The condition does not occur.
- I1
- CE1DBI or CE1SSU failed the integrity check--that is, ordinal number
plus complement not equal to X'FF'.
- I3
- The SS or SSU name supplied in 'Rx' cannot be found in subsystem
attribute table or the subsystem user table, respectively.
- O1
- The specified SS is indicated as inactive in CTKM.
- O2
- The parent SS of the specified SSU is indicated as inactive in CTKM, or,
the parent SS of the specified SSU is active but the specified SSU is
indicated as dormant in MS0UT.
- System errors can result from the following conditions:
- Invalid MDBF ID - The 'INVLID' error condition occurred.
- Maximum MDBF ID exceeded - The 'EXCD' error condition
occurred.
- MDBF ID not available- The 'NOTAVL' error condition
occurred.
- UATBC CP register save area in use - The UATBC macro was issued from a
C-Type segment when the UATBC CP register save area was in use. Only
one UATBC macro issued from a C-Type segment can be serviced at time.
Programming Considerations
- This macro can be executed on any I-stream.
- The UATBC macro requires a minimum of eight bytes of storage when issued
by E-type programs and a minimum of ten bytes of storage when issued by C-type
programs. Four additional bytes of storage are required for each user
exit coded.
- The UATBC macro expansion is independent of the operating
environment. However, the macro service routine provided for a system
generated with the MDBF option is different from that provided for a system
generated without the MDBF option.
- Valid registers for the macro parameters are listed below:
- E-type programs
R0-R7
- C-type programs
R0-R8, and R9 if IDLOC=(E,x,x) is not coded. That is, R9 is valid
for C-Type programs only if it does not contain an ECB address.
- The sequence of processing keywords that contain a register specification
is IDLOC, NAME, COUNT. If the same register was specified for more than
one of these keywords, control will return from the macro with the register
containing data from the last keyword processed. For
example, if R6 is specified for both IDLOC and NAME, upon return from the
macro, R6 will contain a SS name and not an SSUT slot address.
Examples
None.