Use this system macro to change the identifiers (IDs) in the ECB CE1SSU and
CE1DBI fields, which allows access to the databases of other subsystems (SSs)
and subsystem users (SSUs). You can use this macro and the UATBC macro
together to obtain information about any SS or SSU in the TPF system.
See the examples that follow. Also see TPF General
Macros for more information about the UATBC macro.
The CEBIC macro has the following functions:
- Changes the current database ID (DBI) and the current subsystem user ID
(SSU ID).
- Saves the DBI and SSU ID before modification so it can return to the
originating SS or SSU.
- Restores the previously saved DBI and SSU ID for return to the originating
SS and SSU.
In a multiple database function (MDBF) environment, the SSU and the parent
SS to which an entry control block (ECB) belongs are specified by the IDs in
the ECB CE1SSU and CE1DBI fields, respectively. A program can access
only the database of the SS or SSU to which its ECB belongs. That is,
global and fixed file accesses are based on the SSU ID specified in the CE1SSU
field. Other main storage data and random pool accesses are based on
the SS ID specified in the CE1DBI field.
Required Authorizations
|
Key0
| Restricted
| System
| Common Storage
|
| X
|
|
|
Format
Notes:
- id
- saverestore
- label
- A symbolic name can be assigned to the macro statement.
- id
- This is a required parameter.
This specifies whether the current subsystem data base ID or the current
subsystem user ID (or both) are to be changed.
- DBI
- Specifies that the current subsystem data base ID and the current
subsystem user ID are to be changed. For type E programs, register 14
contains the MDBF ID to which the DBI is to be changed. For C-type
programs, the CPREG parameter contains the MDBF ID to which the DBI is to be
changed. The subsystem user ID is changed to the first or only SSU ID
in the new subsystem.
- SSU
- Specifies that the current subsystem user ID is to be changed. If
the new SSU ID does not reside within the current subsystem data base ID
(CE1DBI) then the DBI is changed to the parent subsystem of the new
SSU.
- BSS
- Specifies that the current subsystem data base ID is to be changed to the
BSS data base ID and the current subsystem user ID is to be changed to the
first or only SSU in the basic subsystem (BSS). For E-type
programs, any other parameters coded on the macro call will cause assembly
errors. For C-type programs, the ERR parameter is required and the
CPREG parameter is optional. If coded, the CPREG parameter is
ignored. Any other parameters coded on the C-type macro call will cause
assembly errors.
- saverestore
- This optional parameter indicates whether the current DBI and SSU ID are
to be saved or restored during this macro call.
- S
- This specifies that the current DBI and SSU ID are to be saved prior to
modification. This option is independent of the request type coded for
the id. No mechanism is provided for saving only the DBI or only the
SSU ID.
- R
- Specifies that the current DBI and/or SSU ID are to be restored with the
DBI and/or SSU ID last saved by a CEBIC macro call, respectively. If
'id' is DBI, both the DBI and SSU ID are restored. If
'id' is SSU, only the SSU ID is restored.
- CPREG=Rx
- This parameter is required on C-type macro calls unless id is BSS
or saverestore is R. (In these two cases this parameter is
optional, and it is ignored if coded.) It specifies the register
containing the SS or SSU ID to which the current DBI/SSU ID is to be
changed. The CPREG parameter is not valid on E-type macro calls
and use of this parameter by an E-type program will result in an
assembly error.
- ERR=label
- This parameter is required on all C-type macro calls and is not valid on
all E-type macro calls. It specifies the label to be used for
error exit. Use of this parameter by an E-type program will
result in an assembly error.
Entry Requirements
- E-Type Programs:
- R9 must contain the address of the ECB being processed.
- R14 must contain a 2 byte MDBF ID, right-justified (1-byte complement and
1-byte ordinal number) on all calls except when id is BSS or
saverestore is R. The high-order 2 bytes of the register are
irrelevant.
- C-Type Programs:
- The issuing program must be in supervisor state.
- R9 must contain an ECB address.
- The register specified in CPREG must contain a 2-byte MDBF ID,
right-justified (1-byte complement and 1-byte ordinal number) on all calls
except when id is BSS or saverestore is R. The
high-order 2 bytes of the specified register are irrelevant.
Return Conditions
- Normal Return Condition:
- Control is returned to the next sequential instruction following the macro
call.
- R0 through R9 are unchanged.
- The contents of general registers 14 and 15 are unknown.
- The ECB fields CE1DBI and CE1SSU are changed to the requested subsystem
and subsystem user as defined in Format.
- If the original SSU ID is changed, the global base addresses CE1GLA and
CE1GLY in the ECB are modified to reflect the new SSU.
- If the DBI is changed, its active ECB counter (CA2NEB) is decreased by 1
and the active ECB counter of the new SS is increased by 1.
- Error Return:
Programming Considerations
- This macro can be run on any I-stream.
- This macro can be called from either E-type or C-type programs.
- The macro expands to an SVC for E-type programs.
- The macro expands to a BASSM for C-type programs.
- This macro does not alter the program base identifier (CE1PBI).
- The CEBIC macro expansion is independent of the operating
environment. However, the macro service routine provided for a system
generated with a MDBF environment is different from that generated for a
system without such an environment.
- Data base destruction can occur if care is not exercised in the use of
this macro. If, for example, a record was found with an SSU ID and
later filed after the SSU ID was changed, data base destruction may
occur.
- The SAVE option is independent of the request type. That is, on
both DBI and SSU requests, the SAVE option causes both the current DBI and the
current SSU to be saved before modification.
- There is no mechanism for restoring only the DBI. On a DBI request,
the restore option restores both the DBI and SSU. On an SSU request,
the restore option restores only the SSU ID.
- Valid registers for the CPREG parameter are R0 through R8.
- To avoid the condition that raises a system error the CEBIC macro should
not be issued from a CP program that is interruptible.
Examples
The following example from an E-type segment is based on a MDBF system
configured as follows.
SS Name
| SS MDBF ID
| SSU Name
| SSU Mass ID
|
BSS
| FF00
|
SSU1
SSU2
|
FF00
FE01
|
SS1
| FE01
|
SSU3
SSU4
SSU5
|
FD02
FC03
FB04
|
SS2
| FD02
| SSU6
| FA05
|
Assume that upon entry to the code sequence CE1DBI FF00 (BSS) and CE1SSU
FE01 (SSU2), and that these fields must be unchanged upon exit. The
example illustrates one method of how the CEBIC macro can be used with the
UATBC macro to obtain the names of all subsystem users in the next active
subsystem.
MS0UT REG=R2 06-SSUT ADDRESSABILITY
LEBIC DBI,R2,CHECK=NO GET CURRENT SSORDINAL NUMBER
(See Note 1)
NEXT LA R2,1(,R2) BUMP TO NEXT SS
(See Note 2)
UATBC IDLOC=(R,SSI,R2), CHECK VALIDITY OF NEXT SS
EXCD=SSTOOBIG, ..TOO BIG, WE ARE FINISHED
INVLID=SSNEG, ..SS IS INVALID
NOTAVL=SSINACT, ..SS IS INACTIVE
COUNT=R3 ..NUMBER OF SSUs IN SS
(See Note 3)
LH R14,MU0DPI SS ID OF NEXT SS
(See Note 4)
CEBIC DBI,S SAVE CURRENT SS &
..BUMP ENTRY TO NEXT SS
(See Note 5)
LOOP UATBC IDLOC=(E,SSU,R2), GET THE SSUT ADDRESS FOR ID
NOTAVL=SSUDORM ..IN CE1SSU
(See Note 6)
WTOPC TEXT='SSU NAME IS....',
SUB=(CHARA,MU0NAM)
SSUDORM DS 0H
LA R2,MU0LEN(,R2) BUMP TO NEXT SSUT SLOT
(See Note 7)
BCT R3,LOOP LOOP THRU ALL SSUs FOR THIS
SS (See Note 8)
CEBIC DBI,R RESTORE DBI & SSU ID TO
ORIGINAL (See Note 9)
SSTOOBIG DS 0H THIS SS IS LAST, NEXT IS
TOO BIG
SSNEG DS 0H INPUT SS IS INVALID
EXITC
SSINACT DS 0H SS IS INACTIVE;
B NEXT ...TRY NEXT ONE
Notes:
- The following shows the input and the output for Note 1.
- Input:
- CE1DBI FF00
- Output:
- R2 00 (high-order 3 bytes irrelevant)
- The following shows the input and the output for Note 2.
- Input:
- R2 00 (first time through loop)
- Output:
- R2 01
- The following shows the input and the output for Note 3.
- Input:
- R2 01 R3 irrelevant
- Output:
- R3 3 (number of SSus in SS1)
- The following shows the input and the output for Note 4.
- Output:
- R14 FE01
- The following shows the input and the output for Note 5.
- Input:
-
CE1SDBI irrelevant
CE1DBI FF00
CE1SSU FE01
R14 FE01
- Output:
-
CE1SDBI FF00 FE01
CE1DBI FE01
CE1SSU FD02
- The following shows the input and the output for Note 6.
- Input:
-
R2 irrelevant
CE1SSU FD02
- Output:
- R2 SSUT slot address of SSU3
- The following shows the input and the output for Note 7.
- Input:
- First time through loop R2 SSU slot address of SSU3
- Output:
- First time through loop R2 SSUT slot address of SSU4
- The following shows the input for Note 8.
- Input:
- First time through loop R3 3
- The following shows the input and the output for Note 9.
- Input:
-
CE1DBI FE01
CE1SSU FB04
CE1SDBI FF00 FE01
- Output:
-
CE1DBI FF00
CE1SSU FE01