GETFA

Return file attributes

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall GETFA(channel, keyword, field)

Arguments

channel

An expression that evaluates to a channel number, as specified in a previous OPEN statement. (n)

keyword

An expression that contains the file attribute to be returned. (See the Discussion below for a list of valid keywords.) (a)

field

The variable that will be loaded with the numeric code of the file attribute specified in keyword. (n or a)

Discussion

The GETFA subroutine returns the attributes of a file. You will get unpredictable results if you specify attributes in keyword that are not characteristic of the file or device.

The following table lists the valid keywords, their corresponding file attributes, the operating systems on which they are available, and whether they require a local file system or will work on both local and remote.

GETFA Keywords

Keyword

File attribute

Value returned in field

OS

System

ALQ

Number of 512-byte blocks

The number of 512-byte blocks allocated to the file.a (n)

All

Local

BDT

Backup date and time

The backup date and time, or blanks if none exists.b (a)

VMS

Local

BKS

Bucket size

0 – 63 for indexed or relative files.

0 for all other files.

VMS

Local

CDT

Creation date and time

The creation date and time, or blanks if none exists.b (a)

All

Local

DEQ

Default extension quantity

The default extension quantity. (n)

VMS

Local

EBK

End-of-file block

The end-of-file block. (n)

VMS

Local

EDT

Expiration date and time

The expiration date and time, or blanks if none exists.b (a)

VMS

Local

FAB

Address of the file access block for the channel

The FAB address. (n)

VMS

Local

FFB

First free byte

The first free byte.a (n)

All

Local

GRP

Group decimal number of the file owner

The group number. (n)

All

Local

HBK

Highest virtual 512-byte block

The highest virtual 512-byte block.a (n)

All

Local

IDKc

Duplicate key flag (indicates whether duplicate keys are allowed for the current key of reference)

0 = Duplicate keys not allowed

1 = Duplicate keys allowed

All

Local, Remote

IKLc

Length for the primary key

The length of the primary key within the record. If the key is segmented, this is the length of the first segment. (n)

All

Local, Remote

IKPc

Position for the primary key

The relative position of the primary key within the record. The position of the first byte is 1. If the key is segmented, this is the position of the first segment. (n)

All

Local, Remote

ISZ

Native integer size of the operating system

0 = 32 bit

1 = 64 bit

2 = 128 bit

All

Local, Remote

KRFc

Key of reference

The current key of reference number. (n)

All

Local, Remote

MEM

Member decimal number of the file owner

The member number. (n)

All

Local

NDN

Endian system

0 = File resides on a little-endian system

1 = File resides on a big-endian system

All

Local, Remote

NKYc

Number of keys

The number of keys defined for the file. (n)

All

Local, Remote

OMD

Synergy DBL OPEN mode

mode:submode (where mode is A, U, I, or O, and submode is S, R, I, B, P, or C). (a)

All

Local, Remote

ORG

File organization

0 = Sequential file

16 = Relative file

32 = Indexed file

On OpenVMS, the code returned is the RMS FAB ORG value.

All

Local, Remote

OST

Operating system type of the file system

1 = UNIX

2 = OpenVMS

3 = Windows

All

Local, Remote

PLGc

File prologue level

The file prologue level for an indexed file (2 or 3). (n)

VMS

Local

PRG

Programmer octal number of the file owner

The programmer number. (n)

All

Local

PRJ

Project octal number of the file owner

The project number. (n)

All

Local

PRO

Protection code returned as a 16-digit string of ones and zeros

The protection code. (n)

VMS

Local

RAB

Address of the record access block for the channel

The RAB address. (n)

VMS

Local

RAT

Record attributes

0 = No carriage control

1 = FTN - FORTRAN carriage control

2 = CR - RMS carriage control

4 = PRN - print file VFC carriage control

8 = BLK - records do not cross block  boundaries; sequential files only

The code returned is the RMS FAB RAT value. BLK can be combined with other values.

VMS

Local

RDT

Revision date and time

The revision date and time, or blanks if none exists.b (a)

All

Local

RFA

Record file address

The six-byte binary record address that uniquely identifies a record within a file of any organization. (a6)

All

Local, Remote

RFM

Record format

0 = UDF - undefined

1 = FIX - fixed-length

2 = VAR - variable-length

3 = VFC - variable-length with fixed control

4 = STM - stream format

5 = STMLF - stream format delimited by LF character

6 = STMCR - stream format delimited by CR character

The code returned is the RMS FAB RFM value.

VMS

Local

RMT

Remote or local status

0 = File is local

1 = File is remote

All

Local, Remote

ROP

RMS record options flags

The ROP bits from the RAB. (n)

VMS

Local

RSZ

Record size

The record size in bytes. This value is the actual size of fixed-length records or the maximum size of variable-length records. On OpenVMS, the value returned is the RMS FAB MRS value. (n)

All

Local, Remote

SCH

System channel number

The channel number assigned by the system (used for terminals only). (n)

VMS

Local

SCI

System input channel

The input channel number. (n)

VMS

Local

SCM

System mailbox channel

The mailbox channel number. (n)

VMS

Local

SCO

System output channel

The output channel number. (n)

VMS

Local

SLC

Socket-level cipher

The cipher being used (for example, “AES256-GCM-SHA384” if field is a20). Field can be up to a128 and will contain additional cipher information if a larger buffer is passed (for example, “AES256-GCM-SHA384  TLSv1.2 Kx=RSA   Au=RSA  Enc=AESGCM(256) Mac=AEAD”). (a)

All

Remote

SLE

Socket-level encryption

1 = Channel is encrypted

0 = Channel is not encrypted

All

Remote

UIC

Owner UIC (as numeric)

The owner UIC. (n)

All

Local

VER

Synergy version of the facility accessing the file or device

The seven-byte alpha Synergy version. (a)

All

Local, Remote

XAB

Address of the extended attribute block for the channel

The XAB address. (n)

VMS

Local

XFP

Round-trip packets issued on a channel opened to a remote file

Total number of round-trip packets to and from xfServer since the OPEN. (n)

All

Remote

XFR

Bytes received on a channel opened to a remote file

Total number of bytes from xfServer since the OPEN. (n)

All

Remote

XFS

Bytes sent on a channel opened to a remote file

Total number of bytes sent to xfServer since the OPEN. (n)

All

Remote

XFT

Bytes sent and received on a channel opened to a remote file

Total number of bytes sent to and received from xfServer since the OPEN. (n)

All

Remote

a. On ISAM (Windows and UNIX), this is the size of the index file only.

b. The date and time are represented in the following format: DD-MMM-YYYY hh:mm:ss[.cc], where DD is the day, MMM is the month abbreviation (for example, JAN), YYYY is the four-digit year, hh is the hour, mm is the minute, ss is the second, and cc is the hundredth of a second, if supported.

c. Applies to indexed files only.

We suggest you use the GETRFA qualifier on I/O statements like READ, FIND, and so forth, instead of using the RFA keyword.

You can use the %ISINFO routine to access additional ISAM-specific information.

Important

See the Important note in Error trapping for information about inconsistencies that may occur after an I/O error is encountered.

On UNIX, PRJ and GRP both return the group ID of the file’s group, and PRG and MEM both return the user ID of the file’s owner. (The only difference is that PRJ and PRG return an octal value, while GRP and MEM return a decimal value.) The UIC value is comprised of the MEM and GRP values (in other words, the group ID and the user ID concatenated).

On Windows, PRJ, GRP, PRG, MEM, and UIC all return 0.

Examples

main build_msg_file
record
    src_date            ,a23
    obj_date            ,a23
    exe_date            ,a23
proc
    open(1, i, "vms_msgs.msg") [$ERR_FNF=quit]
    open(2, i, "vms_msgs.obj") [$ERR_FNF=make_um]
    open(3, i, "vms_msgs.exe") [$ERR_FNF=make_um]
    xcall getfa(1, "RDT", src_date)             ;Check revision date of msg src
    xcall getfa(2, "RDT", obj_date)             ;Check revision date of msg obj
    xcall getfa(3, "RDT", exe_date)             ;Check revision date of msg exe
    if (src_date.gt.exe_date) .or. (src_date.gt.obj_date)
      begin
make_um,
        xcall make_msgs                         ;Create new message files
      end
quit,
    stop
endmain