gtpc2m22C/C++ Language Support User's Guide

face_facs-File Address Generation

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