gtpc2m22 | C/C++ Language Support User's Guide |
This function initializes a FARW with the data necessary to access a fixed
file record.
Format
#include <tpfio.h>
int face_facs(unsigned long record_ordinal, const char *record_type_name,
unsigned long record_type_id, enum t_lvl level,
unsigned long *rtnord);
- record_ordinal
- The ordinal number of the fixed file record.
- record_type_name
- A string containing the name of the fixed file record type. It may
optionally be padded to the right with blanks. If this parameter is
coded as NULL, the record_type_id parameter is used to determine
the fixed file record type.
- record_type_id
- The record type ID number for the fixed file record. This parameter
is only used to determine the fixed file record type when record_type_name is
coded as NULL; if record_type_name is not NULL,
record_type_id should be coded as zero.
- level
- One of 16 possible values representing a valid data level from enumeration
type t_lvl, expressed as Dx, where
x represents the hexadecimal number of the level (0-F).
This parameter specifies the file address reference word (FARW) into which the
SON address corresponding to the specified record ordinal and record type will
be placed. Once modified by this function, the contents of this data
level should not be altered by the application.
- rtnord
- The address of an unsigned long into which, on successful completion, the
face_facs() function stores the maximum ordinal number for the
specified record type. If face_facs() returns with the error
condition FACE_FACS_RECORD_ORDINAL_GAP, the next valid ordinal
after record_ordinal is returned in rtnord.
Normal Return
Zero.
Error Return
- FACE_FACS_RECORD_TYPE_NOT_IN_USE
- The record_type_name or record_type_id value passed
to the face_facs() function is not valid because the requested
record type is not in use.
- FACE_FACS_INVALID_RECORD_TYPE
- The record_type_name or record_type_id value passed
to the face_facs() function is not valid because the requested
record type is not defined or it exceeds the limit.
- FACE_FACS_RECORD_TYPE_EMPTY
- The record_type_name or record_type_id value passed
to the face_facs() function is not valid because there are no
records defined for the requested record type in the associated SSU.
- FACE_FACS_INVALID_RECORD_ORDINAL
- The record_ordinal value passed to the face_facs()
function is not valid for the specified record type because it exceeds the
record type limit.
- FACE_FACS_RECORD_ORDINAL_GAP
- The record_ordinal value passed to the face_facs()
function is not valid for the specified record type, but it does not exceed
the record type limit. rtnord contains the next valid
ordinal after record_ordinal. (This return can occur for
pools with PSON gaps.)
- FACE_FACS_INVALID_DATA_LEVEL
- The level value passed to the face_facs function is
not a valid data level (D0-DF).
Programming Considerations
For information about converting record type equates in assembler to C
#defines, see Programming Considerations.
Examples
The following example generates a SON address for "#PROG1"
record number 235 and stores it in the FARW for data level D6.
#include <tpfio.h>
·
·
·
unsigned long prog1_ordinal;
int rc = face_facs(235, "#PROG1", 0, D6, &prog1_ordinal);
switch (rc)
{
case 0: /* Success: the FARW at data level D6 contains the */
/* file address for "#PROG1" record ordinal number */
/* 235, and prog1_ordinal contains the maximum record */
/* ordinal for #PROG1 fixed file records. */
·
·
·
break;
case FACE_FACS_RECORD_TYPE_NOT_IN_USE:
·
·
·
break;
case FACE_FACS_INVALID_RECORD_TYPE:
·
·
·
break;
case FACE_FACS_RECORD_TYPE_EMPTY:
·
·
·
break;
case FACE_FACS_INVALID_RECORD_ORDINAL:
·
·
·
break;
case FACE_FACS_RECORD_ORDINAL_GAP:
/* prog1_ordinal contains the next valid ordinal after */
/* 235. */
·
·
·
break;
case FACE_FACS_INVALID_DATA_LEVEL:
·
·
·
break;
}
Related Information