This general macro writes a record to a file from storage. The block
of storage referred to at the specified ECB data level or data event control
block (DECB) is not removed from the entry control block (ECB). The
control program writes the record on the duplicate copy if one exists.
This macro can be used to file a record that resides in either the virtual
file access (VFA) or on an external device.
The FILNC macro does not return a block of storage to any storage
pool.
Format
- label
- A symbolic name can be assigned to the macro statement.
- datalevel
- An ECB data level (D0-DF) that identifies the file address and core
block information for the I/O request.
- DECB=(reg)|label1
- The label or general register (R0-R7) containing the address of the
DECB, which specifies the file address and core block information for the I/O
request.
- TAG
- Specify one of the following:
- Y
- The name of the segment that issued the FILNC is put into the storage
block to be filed.
- N
- This field is not set.
The default is Y.
- GDS
- Specify one of the following:
- N
- The file address in the specified ECB data level or DECB is for a record
from the online database.
- Y
- The file address in the specified ECB data level or DECB is for a record
on either a general file or a general data set.
Entry Requirements
- R9 must contain the address of the ECB being processed.
- A block of storage must be held by the ECB at the specified ECB data level
(datalevel) or DECB.
- A file address, record ID, and a record code check (RCC) must be contained
in the file address reference word (FARW) for the specified ECB data level
(datalevel) or DECB.
- The GDSRC macro must be executed to set up the file address before FILNC
is used to access a general data set record.
Return Conditions
- Control is returned to the next sequential instruction.
- The contents of R14 and R15 are unknown. The contents of all other
registers are preserved across this macro call.
- If this macro is called from a program running in 24-bit mode, the
condition code will be saved across this macro call. If the macro is
called from a program running in 31-bit mode, the condition code upon return
from this macro is unknown.
- The FARW at the specified ECB data level (datalevel) or DECB is
unchanged.
- The status of the operation is unknown.
- The program identification was placed in the header of the record unless
TAG=N was specified.
- The block of storage at the specified ECB data level (datalevel)
or DECB is not available. The control program makes it available on
return the next time the WAITC macro is run.
Programming Considerations
- This macro can be run on any I-stream.
- A check is made by the control program to determine if the ECB is holding
a block of storage at the specified ECB data level or DECB. In
addition, the record ID at the specified ECB data level or DECB is checked
with the record ID in the record. If any condition is violated, control
is transferred to the system error routine. If an incorrect file
address is detected, the error indicator is set (CE1SUD or IDECSUD) and
control is returned to the calling program. When the RCC in the FARW is
zero, the control program ignores verification of the RCC. If the RCC
is nonzero, the control program verifies that the code specified in the FARW
is the same as the code in the header of the record. If the codes are
not equal, control is transferred to the system error routine.
- The operational program must not use the specified ECB data level
(datalevel) or DECB on return from the control program.
- To ensure completion of the operation a WAITC macro must be
executed.
- An error is posted at WAITC time only if neither copy of the record was
successfully updated.
- If the FILNC is issued from a utility program, specifying TAG=N prevents
the utility program name from being inserted in the storage block for
filing. This allows the segment name performing the data manipulation
to be inserted before the call to the utility routine is made, FILNC is issued
and the name is filed with the data.
- You cannot call the FILNC macro on a record that is part of the suspended
commit scope for an ECB. The following sequence will cause a system
error:
- TXBGC
- FILNC record x
- TXSPC
- FILNC record x.
- TPF transaction services processing affects FILNC macro processing in the
following ways:
- The FILNC actions that are controlled by the record ID attribute table
(RIAT) indicators are set at FILNC time (when the record is filed), but do not
take place until the record has been committed.
- Hardening (that is, writing) to the DASD surface will occur only at commit
time.
- When a group of updated records is hardened to DASD, the filing sequence
that was originally specified by the application program is maintained.
Therefore, applications that rely on a specific sequence of FILNC and WAITC
macros to control the order of updates in a chain of related records will not
lose this ability when placed in a commit scope.
- FILNC macro changes are discarded and hardening does not occur after a
TXRBC macro is called. The DASD surface remains unchanged.
- If a system error occurs because of an ID or record code check, processing
ends as if a TXRBC macro was called.
- The WAITC macro does not report hardware-related filing errors when the
FILNC macro is called in a commit scope. The block of storage at the
specified level is available on return from the FILNC macro. Commit
processing issues an implied WAITC macro.
- Files to general files or general data sets are not considered part of the
commit scope and are not affected by commit scope processing.
- If the location of the data event control block specified by the DECB
parameter does not refer to a valid DECB, control is transferred to the system
error routine.
Examples
None.