% VAX-11 Librarian V03-00@`+ Ɲl+5NZAction_RoutinesZBasicError_Signaling\ FILE_ROUTINES  Internals IntroductionH Misc_routines @ ParametersPascalr*RECORD_ROUTINESH RMS_ALLDEFV RMS_DATDEF RMS_FABDEFlRMS_Info: RMS_KEYDEF3F RMS_NAMDEFO RMS_PRODEF$\ RMS_RABDEFZ RMS_RDTDEFj+1 Introduction) RMS INTERFACE' Version 1? A software package that provides convenient and efficient@ access to the VAX/VMS Record Management Services (RMS) for- high level languages@ This help library is a collection of the "how to" sections? from the user's manual for the RMS Interface subroutines. Synopsis of main keywords:F ACTION_ROUTINES -- Explains  how to specify subroutines to be invokedB based upon the success/failure of a particular RMS interface subroutine.8 BASIC -- Explains how to use RMS interface with Basic.; ERROR_SIGNALING -- Explains how RMS Interface signals the user of error conditions.: FILE_ROUTINES -- Explains how to use the file processing+ subroutines provided by RMS Interface.> INTERNALS -- Describes some of the more technical aspects ofA the internal data structures and programmin g techniques used in RMS Interface.A MISC_ROUTINES -- Describes a few utility subroutines that would) be commonly used with RMS interface.@ PARAMETERS -- Describes how to pass parameters to the position independent subroutines.; PASCAL -- Explains how to use RMS Interface with Pascal.A RECORD_ROUTINES -- Describes and explains how to use the record- processing subroutines of RMS Interface.B RMS_ALLDEF -- Explains how to initialize/modify an XABALL bloc k.B RMS_DATDEF -- Explains how to initialize/modify an XABDAT block.> RMS_FABDEF -- Explains how to initialize/modify a FAB block.H RMS_INFO -- Explains how to use the file inquiry subroutine, RMS_INFO.B RMS_KEYDEF -- Explains how to initialize/modify an XABKEY block.> RMS_NAMDEF -- Explains how to initialize/modify a NAM block.B RMS_PRODEF -- Explains how to initialize/modify an XABPRO block.> RMS_RABDEF -- Explains how to initialize/modify a RAB block.B RMS_RDTDEF -- Explains how to initialize/modify an XABRDT block.wwaj+ 1 ParametersD There are generally 2 methods of passing arguments to the positionA independent RMS Interface subroutines. That being 1) Within a 4 function call and 2) as a "free" character string.2 Function_callH Passing parameters within functionsH obviates the need to specify call arguments in any predeterminedH order. There is a short form and a long form for each function.H (Function calls that define fields within all XAB's other than anH XABKEY exist only in the short form). For example, to specify thatH the argument you are passing is the name of the file (as you justH saw), you can use the long form of the function (FILE_NAME_), or theH short form (in this case, FNM_). So, the two following statements are equivalent: < CALL RMS_OPEN( FILE_NAME_( 'INFO.DAT' )...6 CALL RMS_OPEN( FNM _( 'INFO.DAT' )... H Note that the short form (FNM_) is simply the mnemonic used by RMS forH file name, followed by an underscore. This convention for specifyingH the short form is employed whenever possible (which turns out to be almost every case).3 IFI_H Becoming familiar with the IFI_ function: IFI_ stands forH "Internal File Identifier". This function must (almostH always...explanation in internals section) be included in the call toH all  position INdependent subroutines. For example, if you are going1 to open the file named INFO.DAT, you could say:# INTEGER*4 FILE_IDD CALL RMS_OPEN('FNM=INFO.DAT', IFI_( FILE_ID ), ...H The IFI_ function will store into FILE_ID a particular value that theH RMS Interface routines will use subsequently to identify thisH particular file. There are some rules about the variable sent to theH IFI_ function: 1) It must initially (the first time i t is sent to theH IFI_ function) be zero. 2) It must never be modified by you. 3) ItH need only refer to four contiguous bytes of storage that are initiallyH all zero (ie it does not necessarily have to be Integer*4). 4) ThereH is a synonym for the IFI_ function, namely, the FILE_ function.; Therefore, IFI_(FILE_ID) and FILE_(FILE_ID) are the same.2 Character_StringH Passing parameters as free character strings: This is anotherH method to pass arguments to the RMS Interface routines. It is also aH position independent method. Any argument that may otherwise be sentH within a function call as literal (character) data or as numericalH comstants may instead be specified within a character string that isH NOT passed within a function call. In order for the RMS InterfaceH routines to know what the information in the character stringH specifies, the information is preceeded by the short form of theH function call WITHOUT the underscore, followed by an equal sign (this: is all within the character string). For example, usingH CALL RMS_OPEN( FNM_( 'INFO.DAT' ), ORG_( 'SEQ' ), ... is the same as@ CALL RMS_OPEN( 'FNM=INFO.DAT', 'ORG=SEQ', ... which is also the same as= CALL RMS_OPEN( 'FNM=INFO.DAT; ORG=SEQ', ...H Note the third example has two specifications within the sameH character string: 1) FNM (file name), being INFO.DAT and 2) ORG (fileH organization), being SEQuential. Note that the two specifcations areH separated by a semicolon. As you might expect, you can include asH many specifications within a character string as you wish, as long asH each one is separated from the next by a semicolon. You may use asH many blanks within the character string as you wish, as they areH parsed out in the processing. You may include as many characterH strings in the subroutine call as you like, in any pos ition in theH argument list that pleases you. If you are programming in Pascal,H each character string should be passed within a function call named> STR_. Thus, the above examples would (in Pascal) look like:C RMS_OPEN( FNM_( 'INFO.DAT' ), ORG_( 'SEQ' ), ... is the same asG RMS_OPEN( STR_('FNM=INFO.DAT'), STR_('ORG=SEQ'), ... which is also the same as> RMS_OPEN( STR_('FNM=INFO.DAT; ORG=SEQ'), ...ww j+  1 RMS_FABDEF@ RMS_FABDEF Creates, initializes, and/or updates a? File Access Block associated with the= variable sent to the IFI_ function.2 Function_Calls7 Function calls for initializing/ fields in a FABH Allows freeH Short Function Long Function Type of Argument characterG Name  Name Expected string?D ALQ_ ALLOCATION_QUANTITY_ 4 byte integer by ref. YesD BKS_ BUCKET_SIZE_ 1 byte integer by ref. YesD BLS_ BLOCK_SIZE_ 2 byte integer by ref. YesD FABCTX_ FAB_CONTEXT_ 4 byte integer by ref. YesE DEQ_ DEFAULT_EXTENSION_QUANTITY_ 2 byte integer by ref. YesC DNA_ DEFAULT_NAME_ADDRESS_ (Byte) array by ref. NoD DNS_ DEFAULT_NAME_SIZE_ 1 byte integer by ref. YesD DNM_ DEFAULT_FILE_NAME_ Static Descriptor/ref YesD FAC_ FILE_ACCESS_ Descriptor by ref. YesC FAC_M_ (none) 1 byte mask by ref NoC FNA_ FILE_NAME_ADDRESS_ (Byte) array by ref. NoD FNS_ FILE_NAME_SIZE_ 1 byte integer by ref YesD FNM_ FILE_NAME_ Static Descriptor/ref YesD FOP_ FILE_OPTIONS_ Descriptor by ref YesC FOP_M_ (none) 4 byte mask by ref NoD FSZ_ FIXED_AREA_SIZE_ 1 byte integer by ref YesD GBC_ GLOBAL_BUFFER_COUNT_ 2 byte integer by ref YesD MRN_ MAXIMUM_RECORD_NUMBER 4 byte integer by ref YesD MRS_ MAXIMUM_RECORD_SIZE_ 2 byte integer by ref YesD ORG_ FILE_ORGANIZATION_ Descriptor by ref YesD ORG_V_ (none) 1 byte value by ref  NoE RAT_ RECORD_ATTRIBUTES_ Descriptor by ref YesD RAT_M_ (none) 1 byte mask by ref NoE RFM_ RECORD_FORMAT_ Descriptor by ref YesD RFM_V_ (none) 1 byte value by ref NoE RTV_ RETRIEVAL_WINDOW_SIZE_ 1 byte integer by ref YesE SHR_ FILE_SHARING_ Descriptor by ref YesD SHR_M_ (none) 1 byte mask by ref No 3 Argument_size. Size of ArgumentsD The size of each argument specified is the minimum size thatD an argument may be. All Integer values, whether specified asD 1 byte integer, 2 byte integer, or 4 byte integer, can simplyD default to 4 byte integer (longword) variables within your. program, as can 1 byte masks or values.3 Descriptors D All arguments that are passed as descriptors are expected toD be class S (stati c) or class D (dynamic) character strings.D The address of the character string descriptor is passed to the function.3 Free_character_stringsD These are included in the call to RMS_FABDEF as characterD strings that are not enclosed within a function call. FreeD character strings are position independent. For example, ifD you wanted to specify that the maximum record size was 150D bytes, that the maximum number of records was 2000, and thatD the file options you wanted were CBT and MXV (contiguous best5 try and maximize version), then you could say:B CALL RMS_FABDEF( 'MRS=150; MRN=2000; FOP=CBT,MXV', ... )  3 FAC_D See the section in the RMS manual about specifying fileD access when defining a FAB. The mnemonics used are 'GET,D PUT, DEL, UPD, TRN, BIO, BRO'. You may use any combinationD of these mnemonics in the character string that you send toD the  FAC_ function. Note they are separated by commas. ForD example, if you wanted to specify read and write access to aD file, you could say FAC_('GET,PUT'). If you wish instead toD send the binary 1-byte mask that is actually stored in theD FAB, you can specify that variable (for example) MASK in theD function call to FAC_M_. This would look like FAC_M_(MASK).? If you do not specify file access, default is .3 FOP_D See the section in the RMS manual about specifying fileD processing options. The FOP mnemonics are 'CBT, CIF, CTG,D DFW, DLT, MXV, NAM, NEF, NFS, OFP, POS, RCK, RWC, RFO, SCF,D SPL, SQO, SUP, TEF, TMD, TMP, UFO, WCK'. You may use anyD combination of the FOP mnemonics separated by commas. If youD wish to send the file options by a 32 bit mask, this isD accomplished by using the FOP_M_ function. To clarify, ifD you want to specify file op tions by a character string ofD mnemonics, send the character string to either the FOP_ orD FILE_OPTIONS_ function. If you want to send a preformed, binary mask, use the FOP_M_ function.3 ORG_D See the RMS manual about specifying file organization. TheD mnemonics are 'IDX' or 'REL' or 'SEQ'. Default is SEQ ifD ORG_ is not specified. Only one of the mnemonics should beD used, not a combination. A binary value may be sent insteadD to the ORG_V_ function, which specifies file organization* exactly as it is stored in the FAB.3 RAT_D See the RMS manual about specifying record attributes. TheD mnemonics are one of the following: 'CR' 'FTN' 'PRN' usedD with or without 'BLK'. A binary mask may be sent instead toD the function RAT_M_, which specifies the record attributesD exactly as they are stored in the FAB. Default is 'CR'. To3 specify no record attribute !s, say RAT_(' ').3 RFM_D See the RMS manual about specifying record format. TheD mnemonics are 'FIX' 'STM' 'STMCR' 'STMLF' 'VAR' 'VFC' andD 'UDF'. Only one should be used. A binary value may be sentD instead to the function RFM_V_, which specifies record format= exactly as it is stored in the FAB. Default is 'VAR'.3 SHR_D See the RMS manual about specifying file sharing. TheD mnemonics are a combination of 'PUT, GET, DEL, UP "D, NIL, UPI,D MSE'. A binary mask may instead be sent to the functionD SHR_M_ which specifies file sharing exactly as it is stored in the FAB. 2 ExamplesH Assume the FAB you wanted to initialize was associated with a newH file and the following conditions: 1) Maximum record size of 80H bytes. 2) Maximum number of records: 1000. 3) File name isH INFO.DAT. 4) File access is read, write, and update. 5) File sharingH is allowing only concu #rrent read. 6) Record format is fixed length.H 7) File processing options are 'Create if' and 'Contiguous'. 8) TheH variable in your program that is to be associated with this file isH called TESTFILE. Then the call to RMS_FABDEF could look like any of" the following calling sequences.= CALL RMS_FABDEF( FNM_('INFO.DAT'), FAC_('GET,PUT,UPD'),: SHR_('GET'), RFM_('FIX'), MRS_(80), MRN_(1000),- FOP_('CIF,CTG'), IFI_(TESTFILE) )> CALL RMS_FABDEF( I$FI_(TESTFILE),'FNM=INFO.DAT; RFM=FIX',D 'SHR=GET; FAC=GET,PUT,UPD; MRS=80; MRN=1000; FOP=CIF,CTG')? CALL RMS_FABDEF( FILE_(TESTFILE), FILE_NAME_('INFO.DAT'),6 RECORD_FORMAT_('FIX'), FILE_SHARING_('GET'),@ FILE_ACCESS_('GET,PUT,UPD'), FILE_OPTIONS_('CIF,CTG'),B MAXIMUM_RECORD_SIZE_(80), MAXIMUM_RECORD_NUMBER_(1000) ) also IMPLICIT INTEGER*4 (A-Z) FAB$C_FIX = '00000001'X FAB$M_CIF = '02000000'X %FAB$M_CTG = '00100000'X( MY_FOPS = FAB$M_CIF .OR. FAB$M_CTG8 CALL RMS_FABDEF( IFI_(TESTFILE), FNM_('INFO.DAT'),3 RFM_V_( FAB$C_FIX ), FOP_M_( MY_FOPS ),< 'SHR=GET; FAC=GET,PUT,UPD; MRS=80; MRS=1000' )B ! Note how RFM_V_ is sent a binary value, and FOP_M_ is sent ! a binary mask. ww5j+ 1 RMS_RABDEF@ RMS_RABDEF Creates, initializes, and/or updates aA Record Access Block associated with th &e= variable sent to the IFI_ function.2 Function_Calls 7 Function calls for initializing/ fields in a RABH Allows freeH Short Function Long Function Type of Argument characterG Name Name Expected string?E BKT_ BUCKET_ 4 byte integer by ref. YesE RABCTX_ ' RAB_CONTEXT_ 4 byte integer by ref. YesD RABS_FAB_ (none) 4 byte integer by ref NoD KBF_ KEY_BUFFER_ (Byte) array by ref. NoE KRF_ KEY_OF_REFERENCE_ 1 byte integer by ref YesE KSZ_ KEY_BUFFER_SIZE_ 1 byte integer by ref YesE MBC_ MULTIBLOCK_COUNT_ 1 byte integer by ref YesE MBF_ MULTIBUFFER_COUNT_ 1 byte integer by ref YesD PBF_ PROM(PT_BUFFER_ (Byte) array by ref NoE PSZ_ PROMPT_BUFFER_SIZE_ 1 byte integer by ref YesE RAC_ RECORD_ACCESS_ Descriptor by ref YesD RAC_V_ (none) 1 byte value by ref NoD RBF_ RECORD_BUFFER_ (Byte) array by ref NoD RHB_ RECORD_HEADER_BUFFER_ (Byte) array by ref NoD RFA_ RECORD_FILE_ADDRESS_ 6 contiguous bytes NoE ROP_ RECORD_OPTIONS_ ) Descriptor by ref YesD ROP_M_ (none) 4 byte mask by ref NoE RSZ_ RECORD_BUFFER_SIZE_ 2 byte integer by ref YesE TMO_ TIMEOUT_ 1 byte integer by ref YesD UBF_ USER_BUFFER_ (Byte) array by ref NoE USZ_ USER_BUFFER_SIZE_ 2 byte integer by ref Yes 3 Argument_sizeD The size of each argument specified is the minimum size thatD an argument m *ay be. All Integer values, whether specified asD 1 byte integer, 2 byte integer, or 4 byte integer, can simplyD default to 4 byte integer variables within your program, asD can 1 byte masks or values. High order unused bits are ignored.  3 Descriptors D All arguments that are passed as descriptors are expected toD be class S (static) or class D (dynamic) character strings.D The address of the character string descriptor is passed + to the function.3 Free_character_stringsD These are included in the call to RMS_RABDEF as characterD strings that are not enclosed within a function call. FreeD character strings are position independent. For example, ifD you wanted to specify that the record buffer size was 150D bytes, that the name of the record buffer was BUF (assumeD declared as LOGICAL*1 BUF(150) ), and the record processingD options you want are TPT ,(Truncate on put) and RLK (Lock- Record for write), then you could say:C CALL RMS_RABDEF( 'RSZ=150; ROP=TPT,RLK', RBF_( BUF ) ...)D Note that names of buffers or other variables in your program4 cannot be included in free character strings. 3 RABS_FAB_D This function expects to be sent a 4 byte (Integer*4)D variable whose value is the address of the FAB to which thisD RAB is to be connected when you issue the RMS_CONNECTD - subroutine call. Note that normally you DO NOT NEED to useD this function, as the RAB is otherwise automatically (whenD the file is created or opened) connected to the FABD associated with the same IFI_ variable that you sent toD RMS_RABDEF. The ONLY time you need to use RABS_FAB_ is ifD you want to open a file with multistream access (more thanD one RAB connected to the same FAB). There is an easy butD special way . to handle multistream access to a file, and thatD is explained later in the section on multistream file access.3 RAC_D The descriptor you pass to this function is a characterD string that contains the mnemonic that specifies the type ofD record access you want. The mnemonics are one of theD following: 'SEQ' 'KEY' 'RFA'. See the RMS reference manualD section on record access for further info. Rather than usingD a character strin /g, you may send RAC_V_ an integer variableD or constant that is a value specifying the type of record2 access, exactly as it is stored in the RAB.3 RFA_D This 6 byte array is expected to contain the record's fileD address as returned by RMS to the RAB$W_RFA field in the RABD when a record was retrieved. There is an easy way to obtainD the RFA from a RAB after a record is retrieved, namely byD employing the RMS Interface file inqu 0iry subroutine: (RMS_INFO), described in detail in a later section.3 ROP_D The descriptor sent to this routine is a character stringD that contains a combination of menomics specifying the recordD processing options you want. The mnemonics are anyD combination of 'ASY, CIO, CCO, CVT, EOF, FLD, LOC, KGE, KGT,D LOA, LIM, NLK, NXR, PMT, PTR, RAH, REA, RLK, RNE, RNF, RRL,D TMO, TPT, UIF, ULK, WAT, WBH'. See the RMS reference manualD 1 for more ROP info. Rather than sending ROP_ a characterD string, you may send a 32 bit mask by reference to the ROP_M_ function. 2 ExamplesH Assume you wish to initialize or modify the RAB associated withH the IFI_ variable ASSET_FILE. The conditions you want to set are:H 1) Keyed access. 2) Record processing options of RRL (readH regardless of lock) and NLK (no record locking). 3) The name of theH buffer to receive the record is MYBUF 2. 4) MYBUF is 60 bytes long.H 5) We're keying on the secondary key for this file (key of referenceH is 1, NOT 2, since the primary key of reference is 0). 6) The nameH of the buffer containing the key we want to match is called KEYBUF.H 7) The number of characters in KEYBUF that we want to match on is 10.B Then the call to RMS_RABDEF can look like any of the following:9 CALL RMS_RABDEF( IFI_(ASSET_FILE), RAC_('KEY'),D ROP_('RRL,NLK'), UBF_(MYBUF), U 3SZ_(60), KBF_(KEYBUF),# KSZ_(10), KRF_(1) )G CALL RMS_RABDEF( IFI_(ASSET_FILE), UBF_(MYBUF), KBF_(KEYBUF),? 'ROP=RRL,NLK; USZ=60; KSZ=10; KRF=1; RAC=KEY' )B CALL RMS_RABDEF( FILE_(ASSET_FILE), USER_BUFFER_(MYBUF),; USER_BUFFER_SIZE_(60), KEY_BUFFER_(KEYBUF), : KEY_BUFFER_SIZE_(10), KEY_OF_REFERENCE_(1),D RECORD_ACCESS_('KEY'), RECORD_OPTIONS_('RRL,NLK') ) " IMPLICIT INTEGER*4 (A-Z)!4 RAB$C_KEY = '00000001'X! RAB$M_RRL = '00000008'X! RAB$M_NLK = '00100000'XC CALL RMS_RABDEF( IFI_(ASSET_FILE), UBF_(MYBUF), USZ_(60),B KBF_(KEYBUF), KSZ_(10), KRF_(1), RAC_V_(RAB$C_KEY),4 ROP_M_( RAB$M_RRL .OR. RAB$M_NLK ) )  ww`3k+ 1 RMS_NAMDEF@ RMS_NAMDEF Creates, initializes, and/or updates a7 NAM Block associated with the= va 5riable sent to the IFI_ function. 2 Function_Calls7 Function calls for initializing2 fields in a NAM blockH Allows freeH Short Function Long Function Type of Argument characterG Name Name Expected string?D ESA_ EXPANDED_STRING_ADDRESS_ (Byte) array by ref NoE ESS_ EXPANDED_STRING_SIZE_ 1 6byte integer by ref YesD RLF_ RELATED_FILE_NAM_ 4 byte integer by ref NoD RSA_ RESULTANT_STRING_ADDRESS_ (Byte) array by ref NoE RSS_ RESULTANT_STRING_SIZE_ 1 byte integer by ref Yes 3 ESA_/ESS_D If you wish to utilize the RMS_PARSE subroutine, then ESA_D and ESS_ must be specified by you, since there must be an; array to hold the output from the parsing operation.  3 RLF_D This function expects t7o be sent an integer*4 variable (orD any other 4 byte entity) whose value is the ADDRESS of a NAMD block that is to be used as an extra default level inD processing file specifications for the IFI_ variableD associated with this NAM block. You normally DO NOT NEED toD use this function, unless you wish to employ an extra defaultD level of processing. There is an easy method for obtainingD the address of a NAM block associa 8ted with the "related"D file, namely, using the RMS Interface inquiry subroutineD (RMS_INFO). This is described in detail in the section on RMS_INFO. 3 RSA_D You normally DO NOT NEED to specify a resultant stringD address, as the RMS_NAMDEF subroutine will automaticallyD allocate storage (64 bytes) for holding the resultant stringD of RMS_OPEN, RMS_CREATE, or RMS_SEARCH operations. You canD use the RMS_INFO subrouti 9ne to then access the resultant file name string.3 RSS_D You normally DO NOT NEED to specify a resultant string size,D as this will default to 64 bytes (see RSA_ above). You MUST5 NOT specify RSS_ unless you also specify RSA_. 2 ExamplesH Assume you want to initialize a NAM block with the followingH specifications: 1) A 128 byte array named BUF will serve as theH expanded string buffer. 2) The IFI_ variable associated with this NAMH block : is called TESTFILE. 3) We will use a related NAM block whoseH address is stored in the Integer*4 variable RLF_NAM. Then the call to0 RMS_NAMDEF can look like any of the following:@ CALL RMS_NAMDEF( IFI_(TESTFILE), ESA_(BUF), ESS_(128),, RLF_(RLF_NAM) ), CALL RMS_NAMDEF( FILE_(TESTFILE), : EXPANDED_STRING_ADDRESS_(BUF), 6 EXPANDED_STRING_SIZE_(128),; RELATED_FIL;E_NAM_(RLF_NAM) )@ CALL RMS_NAMDEF( 'ESS=128', IFI_(TESTFILE), ESA_(BUF),- RLF_(RLF_NAM) )  ww,k+ 1 RMS_KEYDEF@ RMS_KEYDEF Creates, initializes, and/or updates aC Key Description Block associated with theB variable sent to the IFI_ function. TheD number of keys you declare is limited only? by the maximum numbe <r RMS can handle. 2 Function_Calls 7 Function calls for initializing3 fields in a XABKEY blockH Allows freeH Short Function Long Function Type of Argument characterG Name Name Expected string?E DAN_ DATA_AREA_NUMBER_ 1 byte integer by ref YesE DFL_ DATA_FILL_SIZE_ 2 byte integer= by ref YesE DTP_ DATA_TYPE_ Descriptor by ref YesD DTP_V_ (none) 1 byte value by ref NoE FLG_ KEY_OPTIONS_FLAG_ Descriptor by ref YesD FLG_M_ (none) 1 byte mask by ref NoE IAN_ INDEX_AREA_NUMBER_ 1 byte integer by ref YesE IFL_ INDEX_FILL_SIZE_ 2 byte integer by ref YesD KNM_ KEY_NAME_ADDRESS_ 32 byte array > NoE LAN_ LOWEST_LEVEL_AREA_NUMBER_ 1 byte integer by ref YesE NUL_ NULL_KEY_VALUE_ 1 byte integer by ref YesE POS_ KEY_POSITION_ Up to 8 2-byte integer Yes? PROLOG_ (none) 1 byte integer by refE REF_ REFERENCE_NUMBER_ 1 byte integer by ref YesE SIZ_ KEY_SIZE_ Up to 8 1-byte integer Yes3 Argument_sizeD The size of each argument specified is the mini ?mum size thatD an argument may be. All Integer values, whether specified asD 1 byte integer, 2 byte integer, or 4 byte integer, can simplyD default to 4 byte integer variables within your program, asD can 1 byte masks or values. High order unused bits are ignored. 3 DescriptorsD All arguments that are passed as descriptors are expected toD be class S (static) or class D (dynamic) character strings.D The address of the character @string descriptor is passed to the function.  3 Free_character_stringsD These are included in the call to RMS_KEYDEF as characterD strings that are not enclosed within a function call. FreeD character strings are position independent. For example, ifD you wanted to specify that the key size was 15 bytes, thatD the key position was the first byte in the record (offset ofD zero), and that the key data type was STG (string), then y Aou could say:; CALL RMS_KEYDEF( 'SIZ=15; DTP=STG; POS=0', ...).  3 DTP_D The character string sent to this function contains one ofD the following mnemonics that defines the type of data for theD key: 'BN2' 'BN4' 'IN2' 'IN4' 'PAC' 'STG'. See the RMSD reference manual for more info on DTP_. If you chooseD instead to send the actual value stored in the XABKEY block; that defines the data type, use the DTP_V_ func Btion.  3 FLG_D The character string sent to this function contains one orD more of the following mnemonics that defines the key optionsD for this key: 'CHG, DAT_NCMPR, DUP, IDX_NCMPR, KEY_NCMPR,D NUL'. See the RMS reference manual for more info on FLG_.D If you choose instead to send the actual 1 byte mask storedD in the XABKEY block that defines the key options use the FLG_M_ function.3 POS_D This function can be Csent up to 8 arguments, each argumentD specifying the offset into the record of that respective keyD segment. For example, if this particular key has 3 segments,D at offsets 0, 20, and 35 in the record, then the functionD call would look like this: POS_(0,20,35). To use a freeD character string, it would look like 'POS=0,20,35'. If theD key had only one segment, starting at offset 10, the functionD call would look like: POS_(10). D To use a free characterD string, it would look like 'POS=10'. Segmented keys can only$ be declared as STG data type.3 REF_D REF_ specifies the key of reference and thus the XABKEY blockD that you are defining. You should always include REF_ in theD call. If you omit it, the key affected will be the keyD specified in the most recent previous call to REF_ (orD SETKRF_, explained later). If no previous calls to REF_ (orD SETKRF_ E) have been executed, the key affected will be reference zero.3 SIZ_D This function can be sent up to 8 arguments, each argumentD specifying the size (in bytes) of that respective keyD segment. For example, if this particular key has 3 segments,D with sizes 10, 5, and 10 in the record, then the functionD call would look like this: SIZ_(10,5,10). To use a freeD character string, it would look like 'SIZ=10,5,10'. If the FD key had only one segment, with a length of 10 bytes, theD function call would look like: SIZ_(10). To use a freeD character string, it would look like 'SIZ=10'. Segmented2 keys can only be declared as STG data type. 2 ExamplesH The IFI_ variable for this file is called FILE_ID. This file isH indexed, and you want to define two keys. One key is data typeH character, 20 bytes in length, and begins in the first byte of theH record G. This key is the primary key for the record. The second keyH is data type Integer*4 (and therefore defaults to 4 bytes in length),H and it's OFFSET into the record is 30 bytes. This key is allowed toH have duplicate entries. Example calls to RMS_KEYDEF to define the two keys follows:E CALL RMS_KEYDEF( IFI_( FILE_ID ), DTP_( 'STG' ), POS_(0),2 REF_(0), SIZ_( 20 ) )H CALL RMS_KEYDEF( IFI_( FILE_ID ), DTP_( 'IN4' ), POS_( 30 ),5 H REF_(1), FLG_( 'DUP' ) )H There is also a method of defining keys within a subroutine callH to either RMS_OPEN or RMS_CREATE. This is done by invoking calls toH the KEY_ function within the calls to the open or create subroutines.H Within each call to KEY_ is included the same information you wouldH include in a call to RMS_KEYDEF. The user has the choice of decidingH his method for defining keys to indexed files. It is essentially aH tr Iade off between several subroutine calls (using RMS_KEYDEF) orH several function calls (using KEY_) within another subroutine call.C For an example of the KEY_ function, see help for for RMS_CREATE. wwIk+ 1 RMS_ALLDEFA RMS_ALLDEF Creates, initializes, and/or updates anG Allocation Block (XABALL) associated with theC variable sent to the IFI_ function. MoreB than one all Jocation area can be declaredB per file (see the RMS reference manual).2 Function_Calls 8 Function calls for initializing5 fields in a XABALL blockH Allows freeH Short Function Type of Argument characterG Name Description Expected string?E AID_ Area identification 1 byte iKnteger by ref YesE ALN_ Alignment Boundary type Char Descriptor by ref YesD ALN_V_ " " " 1 byte value by ref NoE XABALQ_ Allocation quantity 4 byte integer by ref YesE AOP_ Allocation options Char descriptor by ref YesD AOP_M_ " " 1 byte mask by ref NoE BKZ_ Bucket size 1 byte integer by ref YesE XABDEQ_ Default extension quant 2 byte integer L by ref YesE LOC_ Location 4 byte integer by ref YesE VOL_ Relative volume number 2 byte integer by ref YesE RFI_ Relative file identifier 3 arguments, each a Yes? 2-byte integer by ref 3 AID_F The area identification number is unique to a specific XABALLF block, and thus is used to identify a particular XABALL blockF if more than one is declared (which only is l Megal with indexed files).3 ALN_F The character string sent to this function contains one of theF following mnemonics that defines the alignment boundary typeF for a particular file area: 'CYL', 'LBN', 'RFI', 'VBN'. SeeF the RMS reference manual for more info on ALN_. If you chooseF instead to send the actual value stored in the XABALL blockF that defines the alignment boundary type, use the ALN_V_ funtion.3 AOP_F N The character string passed to this function contains one orF more of the following mnemonics that specify the allocationF options you want for a particular file area: 'CBT, CTG, HRD,F ONC'. See the RMS reference manual for more info on AOP_. IfF you choose instead to specify the actual mask stored in theF XABALL block that defines the allocation options, use the AOP_M_ funtion. 3 ExamplesJ Assume you want to initialize an XAOBALL block with the followingJ specifications: 1)Area number (AID) is 2. 2)Allocation quantity is 30J blocks. 3)Alignment begins at logical block number specified by LOCJ field (i.e. alignment boundary type is 'LBN'). 4)Location starts atJ logical block number 1024. 5)Allocation is to be contiguous. If theJ allocation cannot be done as specified, you want an error code returnedJ rather than a best possible approximation performed. This is done byJ using the 'HPRD' option. 6)The IFI variable identifying this file isJ called FILE_ID. The subroutine call to RMS_ALLDEF can look like either of the following:= CALL RMS_ALLDEF( ALN_('LBN'), AID_(2), XABALQ_(30),B IFI_( FILE_ID ), LOC_(1024), AOP_('CTG,HRD') )+ CALL RMS_ALLDEF( IFI_( FILE_ID ),H 'AID=2; XABALQ=30; LOC=1024; ALN=LBN; AOP=CTG,HRD' )  wwUk+ 1 RMS_PRODEF@ RMS_PRODEF Creates, initializes Q, and/or updates aG Protection Block (XABPRO) associated with the? variable sent to the IFI_ function. 2 Function_Calls 8 Function calls for initializing5 fields in a XABPRO blockH Allows freeH Short Function Type of Argument characterG Name Description Expected Rstring?E GRP_ Group number of file owner 2 byte integer by ref YesE MBM_ Member of file owner 2 byte integer by ref YesE MTACC_ Mag tape accessibility 1 byte integer by ref YesE PRO_ File protection Char descriptor by ref YesD PRO_M_ " " 2 byte mask by ref NoE UIC_ UIC of file owner 2 arguments, each a Yes? 2 byte integer by ref S 3 GRP_/MBM_F When you use a character string to specify group and/or member,F note that the ascii conversion to binary is performed as if the1 number is specified as base 10, not octal.3 PRO_F The character string passed to this function requires a formatF that is compatible with the DCL Set Protection command. ForF example, protection against all access except the user, whoF gets full access, would specified as 'S,O:RWED,G,W'. Note TthatF current default access for a particular population (S, O, G, orF W) is assumed if that particular population is not specified inF the character string. Thus, specifying 'O:RWE' will actuallyF result in system, group, and world having the process's defaultF access privilege, while specifying 'O:RWE,S,G,W' will giveF access privilege to only the owner. Also note that aF population is specified by only one letter, and that full wor UdsF (such as "OWNER:RWED" ) are not allowed. If you want to passF the actual binary mask that specifies protection as it is; stored in the XABPRO block, use the PRO_M_ function.  2 ExamplesJ Assume you want to initialize or modify an XABPRO block with theJ following specifications: 1)You have system privilege and you want toJ set the UIC of this file to one other than your own, namely [211,007]J (octal) in this case. 2)You are giving the V new owner of the file allJ forms of access. The system will have read access. All otherJ populations are denied access. 3)The IFI variable that identifies thisJ file is called FILE_ID. The calls to RMS_PRODEF can look like either of the following:> CALL RMS_PRODEF( IFI_( FILE_ID), UIC_('211'o, '7'o),7 PRO_('o:rwed, s:r,g,w') )4 CALL RMS_PRODEF( GRP_('211'o), MBM_('7'o),1 'PRO=O:RWED,S:R,G,W' )  Www^k+ 1 RMS_DATDEF@ RMS_DATDEF Creates, initializes, and/or updates aG Date and Time block (XABDAT) associated with C the variable sent to the IFI_ function.  2 Function_Calls8 Function calls for initializing5 fields in a XABDAT blockH Allows freeH Short Function Type o Xf Argument characterG Name Description Expected string?G BDT_ Backup date and time Char descriptor by ref YesF BDT_V_ " " " " 8 byte abs or delta time NoG CDT_ Creation date and time Char descriptor by ref YesF CDT_V_ " " " " 8 byte abs or delta time NoG EDT_ Expiration date and time Char descriptor by ref YesF EDT_V_ " " " " Y 8 byte abs or delta time NoG RDT_ Revision date and time Char descriptor by ref YesF RDT_V_ " " " " 8 byte abs or delta time NoG RVN_ Revision number 2 byte integer by ref Yes 3 Time_SpecificationF Absolute or delta date and time is to be specified as describedF in the system services manual section on $BINTIM. If you wantF to specify the actual 64 bit quantity that specifies absolute: or Zdelta time, use the corresponding _V_ functions. 2 ExamplesJ Assume you want to initialize or modify an XABDAT block with theJ following specifications: 1)Expiration date and time is ten days fromJ creation date. 2)The IFI variable that identifies this file is calledJ FILE_ID. The call to RMS_DATDEF could look like either of the following:9 CALL RMS_DATDEF( IFI_( FILE_ID ), EDT_('10 ') )6 CALL RMS_DATDEF('EDT=10', IFI_( FILE_ID ) ) w[w`ok+ 1 RMS_RDTDEF@ RMS_RDTDEF Creates, initializes, and/or updates a? Revision Date and Time block (XABRDT)C associated with the variable sent to the * IFI_ function.   2 Function_Calls8 Function calls for initializing5 fields in a XABRDT blockH Allows freeH Short Fu \nction Type of Argument characterG Name Description Expected string?G RDT_RDT_ Revision date and time Char descriptor by ref YesF RDT_RDT_V_ " " " " 8 byte abs or delta time NoG RDT_RVN_ Revision number 2 byte integer by ref Yes   3 Time_SpecificationF Absolute or delta date and time is to be specified as describedF in the system services manual sect ]ion on $BINTIM. If you wantF to specify the actual 64 bit quantity that specifies absolute: or delta time, use the corresponding _V_ functions. ww@:tk+1 FILE_ROUTINES7 Explanation of calling syntaxJ All required parameters are included in the description of the callingJ sequence. Optional parameters are included in a descriptive manner, within square brackets ([]). For example:, [ FAB related functions ^] J means any of the function calls that were described in the section onJ the RMS_FABDEF subroutine. Obviously, the line continuation characters/ used in column 6 in Fortran are omitted here. 2 RMS_CREATEC Function: Create (or Open) a file and establish a record stream " for input and output." Syntax: IOFLAG = RMS_CREATE( / IFI_ (FILE_ID), 9 [ FAB related functions ],9 _ [ RAB related functions ],9 [ NAM related functions ],9 [ FAB, RAB, or NAM related: free character strings ],H [ KEY_( IFI_(FILE_ID), [ XABKEY function calls ] ) ],K [ XABALL_( IFI_(FILE_ID), [ XABALL function calls ] ) ],K [ XABPRO_( IFI_(FILE_ID), [ XABPRO function calls ] ) ],K [ XABDAT_( IFI_(FILE_ID), [ XABDAT function c `alls ] ) ],K [ XABRDT_( IFI_(FILE_ID), [ XABRDT function calls ] ) ], ) 3 Example Example: INTEGER*4 MYFILE$ LOGICAL*1 RECORD_BUF(80)@ IOFLAG = RMS_CREATE( IFI_(MYFILE), FNM_('DATA.DAT'),H FOP_('CIF'), FAC_('GET,PUT,UPD'), ORG_('IDX'),> RFM_('FIX'), MRS_(80), SHR_('NIL'), B RAC_('KEY'), RSZ_(80), RBF_(RECORD_BUF),6 US aZ_(80), UBF_(RECORD_BUF), J XABPRO_( IFI_( FILE_ID ), 'PRO=S:R,O:RWED,G,W'),0 KEY_( IFI_( FILE_ID ),I REF_(0), DTP_('STG'), 'POS=0;SIZ=20' ),0 KEY_( IFI_( FILE_ID ),I REF_(1), DTP_('IN4'), 'POS=30;FLG=DUP' )  ) 0 Explanation of ExampleD A file named DATA.DAT was created if it did not alreadyD exist. Ifb it was in fact created, then is has the followingD characteristics: File access (FAC_) will allow reading,D writing, and updating of records. File organization (ORG_)D is indexed, with two keys (KEY_). Record format (RFM_) isD fixed length with record size (MRS_) of 80 bytes. No fileD sharing (SHR_) is concurrently allowed. Record access (RAC_)D has been initialized as keyed. The input buffer (UBF_) andD output buffer (RBF_) for cthe file are the same, namelyD RECORD_BUF. Therefore, the sizes of the input and outputD buffers (USZ_ and RSZ_) are the same, namely, 80 bytes. FileD protection (PRO_) specifies that the owner will have fullD access, the system only read access, and group and world noD access. The primary key is data type character string, withD offset into record of zero bytes and key size of 20 bytes.D The secondary key is Integer*4 data typ de with offset intoD record of 30 bytes, and this key is allowed to have duplicateD values. On return, IOFLAG will contain the RMS status codeD for either the $CREATE or $CONNECT operations that occurred.D If the $CREATE was successful, then the status code reflectsD the $CONNECT outcome. No NAM block specifications were+ included in this call to RMS_CREATE. 2 RMS_OPEN8 Function: Open a file and establish a record stream < for i enput and output. XABKEY and/or NAM blocks8 do not need to be explicitly declared here. # Syntax: IOFLAG = RMS_OPEN( * IFI_ (FILE_ID), 4 [ FAB related functions ],4 [ RAB related functions ],4 [ NAM related functions ],4 [ FAB, RAB, or NAM related5 free character strings ],H [ KEY_( IFI_(FILE_ID), [ XA fBKEY function calls ] ) ],K [ XABALL_( IFI_(FILE_ID), [ XABALL function calls ] ) ],K [ XABPRO_( IFI_(FILE_ID), [ XABPRO function calls ] ) ],K [ XABDAT_( IFI_(FILE_ID), [ XABDAT function calls ] ) ],K [ XABRDT_( IFI_(FILE_ID), [ XABRDT function calls ] ) ], ) 3 Example : This routine is utilized exactly like the RMS_CREATE: subroutine, except that the file must already exist.* g See the example for RMS_CREATE. 2 RMS_CLOSEA Function: Closes a file. Does not deallocate the file controlF blocks (FAB, RAB, etc) that were allocated for this file. Syntax: IOFLAG = RMS_CLOSE() IFI_ (FILE_ID),4 [ FAB related functions ],@ [ FAB related free character strings ]K [ XABPRO_( IFI_(FILE_ID), [ XABPRO function calls ] ) ],K [ XABRDT_( h IFI_(FILE_ID), [ XABRDT function calls ] ) ], ); Example: IOFLAG = RMS_CLOSE( IFI_(FILE_ID), 'FOP=DLT' )< Explanation: Closes the file associated with IFI_ variable@ FILE_ID and deletes file (since 'DLT' file option was specified).  2 RMS_CLOSEOUTD Function: Closes a file. Deallocates all the file control blocks> (RAB, FAB, etc) that were allocated for the file.0 Syntax: See RMS_CLOSE. They are idenitical. 2 RMS_PARSED Function: Anaylze a file specification string and fill in various NAM block fields.! Syntax: IOFLAG = RMS_PARSE() IFI_ (FILE_ID),4 [ FAB related functions ],4 [ NAM related functions ],3 [ FAB or NAM related free3 character strings ]! ) Example:  INTEGER*4 NEWFILE j( LOGICAL*1 EXPANDED_BUF(128)0 IOFLAG = RMS_PARSE( IFI_(NEWFILE),: 'FNM=DATA.DAT; ESS=128',> ESA_(EXPANDED_BUF) )  2 RMS_SEARCHB Function: Scans a directory file and fills in NAM block fields.8 Should be preceeded by a call to RMS_PARSE.! Syntax: IOFLAG = RMS_SEARCH() IFI_ (FILE_ID),4 [ NAM related functions ],A k [ NAM related free character strings ],# ) Example: INTEGER*4 NEWFILE. LOGICAL*1 FULL_SPECIFICATION(128)H ! Assume the sample call to RMS_PARSE (above) has been done2 IOFLAG = RMS_SEARCH( IFI_( NEWFILE ),F RSA_( FULL_SPECIFICATION ), RSS_( 128 ) )E ! Note that the default resultant string destination and$ ! size were overridden.  l2 RMS_DISPLAYD Function: Put file information (in a previously opened file) into FAB and XAB's." Syntax: IOFLAG = RMS_DISPLAY(1 IFI_ (FILE_ID),H [ KEY_( IFI_(FILE_ID), [ XABKEY function calls ] ) ],K [ XABALL_( IFI_(FILE_ID), [ XABALL function calls ] ) ],K [ XABPRO_( IFI_(FILE_ID), [ XABPRO function calls ] ) ],K [ XABDAT_( IFI_(FILE_ID), [ XABDAT function calls ] ) m ],K [ XABRDT_( IFI_(FILE_ID), [ XABRDT function calls ] ) ],# ) 3 ExampleI Example: ! Assume you want information about the keys associated with4 ! an indexed file that already exists.  INTEGER*4 OLDFILE> IOFLAG = RMS_OPEN( IFI_(OLDFILE), 'FNM=DATA.DAT')I ! Utilize the RMS Interface subroutine RMS_INFO to determineJ ! the number of keys associated with this n file. The mnemonicH ! 'NOK' returns number of keys to next argument in calling  ! sequence.1 CALL RMS_INFO(OLDFILE, 'NOK', NKEYS) H ! Now allocate the correct number of XABKEY blocks for this ! file. DO I = 1, NKEYS> CALL RMS_KEYDEF( IFI_ (OLDFILE), REF_ (I-1) ) END DOA ! Now fill the key blocks with this file's key info.3 IOFLAG = RMS_DISPLAY( I oFI_ (OLDFILE) ) 2 RMS_ENTER, Function: Insert file name into directory.+ Syntax: CALL RMS_ENTER( IFI_(FILE_ID) )C NOTE: The particular file must already have been RMS_PARSE'd,C RMS_SEARCH'ed, or RMS_OPEN'ed or RMS_CREATE'd (and thenE RMS_CLOSE'd) before this routine can be invoked. Thus it= allows no arguments other than the IFI_ function. 2 RMS_ERASE3 Function: Delete file and remove directory entry.* Syntax: CALL RMS_ERASE( IFI_(F pILE_ID),6 [ FAB related functions ],6 [ NAM related functions ],1 [ FAB and NAM related6 free character strings ] )@ Example: Assume you wanted to delete the file associated with% logical name MARKED_FILE. INTEGER*4 FILEA IOFLAG = RMS_ERASE( IFI_(FILE), FNM_('MARKED_FILE') ) 2 RMS_EXTENDA Function: Explicitly i qncrease amount of disk space allocated to a file./ Syntax: IOFLAG = RMS_EXTEND( IFI_(FILE_ID),4 [ FAB related functions ],@ [ FAB related free character strings ]K [ XABALL_( IFI_(FILE_ID), [ XABALL function calls ] ) ], )% NOTE: If there is no allocationA XAB allocated for the file, the extension quantity is< obtained from the ALQ_ (a FAB related)r function. 2 RMS_REMOVE, Function: Remove file name from directory./ Syntax: IOFLAG = RMS_REMOVE( IFI_(FILE_ID),; [ NAM related functions ],G [ NAM related free character strings ] )B NOTE: This routine must be preceeded by the RMS_PARSE and/or, RMS_SEARCH service for the file. 2 RMS_RENAME Function: Rename a file.: Syntax: IOFLAG = RMS_RENAME( OLD_FILE_ID, NEsW_FILE_ID)H NOTE: Previous calls to RMS_FABDEF and/or RMS_NAMDEF for both fileF identification variables are essential in preparation for D calling this routine. Also, the arguments sent to this 1 routine are NOT position independent.  ww`zk+1 RECORD_ROUTINES6 There are two types of record processing subroutines:- 1) Position Independent calling syntax (PI)+ 2) Position Dependent calling syntax (PD)2 PI7 t Explanation of calling syntaxJ All required parameters are included in the description of the callingJ sequence. Optional parameters are included in a descriptive manner, within square brackets ([]). For example:, [ FAB related functions ] J means any of the function calls that were described in the section onJ the RMS_FABDEF subroutine. Obviously, the line continuation characters/ used in column 6 in Fortran are omitted here. 3 Example u Example:5The file we are accessing is associated with the IFI_5variable FILE_ID. Assume the file we are accessing is:indexed. The maximum record size is 80 bytes. We want to:retrieve on the primary key. The primary key is data type<'STG' (character) and is 15 bytes long. We want to retrieve:the first record whose key is greater than or equal to the&contents of the key buffer (KEY_BUF).   INTEGER*4 FILE_ID LOGICAL*1 RECORD_BUF(80) LOGICAL*1 KEY_BUF(15)A I vOFLAG = RMS_GET( IFI_( FILE_ID ), RAC_( 'KEY' ), KRF_( 0 ),@ KBF_( KEY_BUF ), KSZ_( 15 ), ROP_('KGE'),5 UBF_( RECORD_BUF ), USZ_( 80 ) )8 ! Suppose that we wanted to repeat this GET at some6 ! other point, and suppose none of the RAB fields: ! included in the above call have been modified. Then ! you could simply say:( IOFLAG = RMS_GET ( IFI_( FILE_ID) ) 3 RMS_CONNECT<Function: Explicitly establish a w record stream between a RAB9associated with one IFI_ variable and a FAB with the same5or different IFI_ variable. Note that when a file is/RMS_OPEN'ed or RMS_CREATE'd, a record stream is1automatically established between the RAB and FAB9associated with that IFI_ variable. Thus, you do not need1to invoke this subroutine unless you wish to use multiple RAB's with one FAB. =Syntax: IOFLAG = RMS_CONNECT( IFI_( RAB_ASSOCIATED_FILE_ID),2 [ RAB related funtions ], x> [ RAB related free character strings]% ) 4 Example Example:, ! Open an old file with multistream access+ INTEGER*4 OLDFILE, FAB_ADDRESS, EXTRA_RAB6 IOFLAG = RMS_OPEN( IFI_(OLDFILE), 'FNM=OLDFILE.DAT', 'SHR=MSE', ......)> ! One RAB has already been implicitly connected and is ready ! for I/O.< ! Use the RMS Interface inquiry routine to get the address= ! of the FAB for this file. The mnemonic 'FAB y' returns theA ! address of the FAB to the next variable in the argument list.- CALL RMS_INFO( OLDFILE, 'FAB', FAB_ADDRESS)9 ! Define the second RAB to be connected with this file.1 ! Note you MUST use a virgin IFI_ variable, you9 ! MUST establish the address of the mother FAB, and you< ! MUST NOT define any other file control blocks associated7 ! with this new IFI_ variable (ie this is essentially ! a "stand alone" RAB)= CALL RMS_CONNECT( IFI_( EXTRA_RAB), RABS_FAB_(FAB_ADDR zESS),3 [ other RAB related specifications ]... ); ! To do record processing associated with the default RAB: ! connected to the FAB, send IFI_(OLDFILE) to the record ! processing subroutine. 9 ! To do record processing associated with the extra RAB< ! connected to the FAB, send IFI_(EXTRA_RAB) to the record ! processing subroutine.  3 RMS_DISCONNECT1Function: Break connection between a RAB and FAB.=Syntax: IOFLAG = RMS_DISCONNECT ( IFI_( RAB_TO_DISCONNECT),2 { [ RAB related functions ],> [ RAB related free character strings ]# )BExample: Study the example for RMS_CONNECT. Then use the context5 of that example to understand what follows:? To disconnect the default RAB for the file, you would say:2 IOFLAG = RMS_DISCONNECT( IFI_(OLDFILE) )> To disconnect the second RAB for the file, you would say:4 IOFL |AG = RMS_DISCONNECT( IFI_(EXTRA_RAB) ) 3 RMS_DELETE>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual..Syntax: IOFLAG = RMS_DELETE( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ] ) 3 RMS_FIND>Function: The function of this routine is synonymous with the? actual RMS ro }utine as described in the RMS reference manual.,Syntax: IOFLAG = RMS_FIND( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ] ) 3 RMS_FLUSH>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.-Syntax: IOFLAG = RMS_FLUSH( IFI_(FILE_ID),2 [ RAB related ~functions ],> [ RAB related free character strings ] ) 3 RMS_FREE>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.,Syntax: IOFLAG = RMS_FREE( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ] ) 3 RMS_GET>Function: The function of  this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.+Syntax: IOFLAG = RMS_GET( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ] ) 3 RMS_PUT>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.+Syntax: IOFLAG = RMS_PU T( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ ) 3 RMS_READ>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.,Syntax: IOFLAG = RMS_READ( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ )3 RMS_RELEASE>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual./Syntax: IOFLAG = RMS_RELEASE( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ ) 3 RMS_REWIND>Function: The function of this routine is synonymous with the? actual RMS ro utine as described in the RMS reference manual..Syntax: IOFLAG = RMS_REWIND( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ ) 3 RMS_SPACE>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.-Syntax: IOFLAG = RMS_SPACE( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ )3 RMS_TRUNCATE>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.0Syntax: IOFLAG = RMS_TRUNCATE( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ ) 3 RMS_UPD ATE>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual..Syntax: IOFLAG = RMS_UPDATE( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ ) 3 RMS_WAIT>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.,Syntax: IOFLAG = RMS_WAIT( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]$ ) 3 RMS_WRITE>Function: The function of this routine is synonymous with the? actual RMS routine as described in the RMS reference manual.-Syntax: IOFLAG = RMS_WRITE( IFI_(FILE_ID),2 [ RAB related functions ],> [ RAB related free character strings ]  2 PD . NotationGThe following notation conventions are used to describe the argumentsGpassed to these subroutines: "rl" means read only longword; "rw"Gmeans read only word (2 bytes); "rb" mead read only byte; "ab" meansbyte address of a buffer.  3 RMS_BLKREADFunction: Read using Block I/O.:Syntax: IOFLAG = RMS_BLKREAD(FILE_ID.rl, USER_BUFFER.ab,4 USE R_BUFFER_SIZE.rw, 8 VIRTUAL_BLOCK_NUMBER.rl )<Note: The file must have been opened with file access of= 'BIO' or 'BRO'. The first accessible virtual block= is number one (unless you do an RMS_SPACE backwardsA to block zero). A single read can span several blocks.  3 RMS_BLKWRITE Function: Write using Block I/O.=Syntax: IOFLAG = RMS_BLKWRITE(FILE_ID.rl, RECORD_BUFFER.ab,6 RECORD_BUFFER_S IZE.rw, 8 VIRTUAL_BLOCK_NUMBER.rl )<Note: The file must have been opened with file access of= 'BIO' or 'BRO'. The first accessible virtual block= is number one (unless you do an RMS_SPACE backwardsB to block zero). A single write can span several blocks.  3 RMS_FINDKEY4Function: To establish internal pointers to a record?Syntax: IOFLAG = RMS_FINDKEY(FILE_ID.rl, KEY.ab, KEY_SIZE.rb,- KEY_R EF_NO.rb)NOTE:E If only FILE_ID, or FILE_ID and KEY_REF_NO are included in? the call, a sequential find is performed. If KEY isD included, a keyed find is performed. For relative files,? KEY is the relative record number, and KEY_SIZE andF KEY_REF_NO should not be included in the call. For a keyedG find to indexed files, all 4 parameters should be included.  3 RMS_GETDIR Function: G Get a record by relativ e record number using keyed access to? relative files or sequential files with fixed length records. ;Syntax: IOFLAG = RMS_GETDIR( FILE_ID.rl, RECORD_BUFR.ab,A RECORD_SIZE.rw, RECORD_NUMBER.rl) 3 RMS_GETKEY2Function: Gets records from an indexed file by key<Syntax: IOFLAG = RMS_GETKEY( FILE_ID.rl, RECORD_BUFR.ab, = RECORD_SIZE.rw, KEY_BUFR.ab, < KEY_SIZE.rb, KEY_R EF_NUM.rb)A These arguments correspond to the following mnemonics:> IOFLAG = RMS_GETKEY( IFI_, UBF, USZ, KBF, KSZ, KRF) 3 RMS_GETRFA Function: F Get a record by the records file address (a 6 byte entity).;Syntax: IOFLAG = RMS_GETRFA( FILE_ID.rl, RECORD_BUFR.ab,7 RECORD_SIZE.rw, RFA.ab)CNote: The RFA of the record must have been previously obtainedF (i.e. by GETting the record with access other than 'RFA'). F Obtaining the RFA of a record is possible with the RMS_INFO subroutine.   3 RMS_GETSEQ?Function: To get a record from a file in sequential access. 5Syntax: IOFLAG = RMS_GETSEQ(FILE_ID.rl, RECORD.ab,= RECORD_SIZE.rw, KEY_OF_REF.rb)>NOTE: KEY_OF_REF should only be included in the call for  indexed files. 3 RMS_GETVFC 4Function: Reads Variable with Fixed Control records;Syntax: IOFLAG = RMS_GETVFC ( FILE_ID.rl, USER_BUFFER.ab,4 USER_BUFFER_SIZE.rw,9 RECORD_HEADER_BUFFER.ab, ; RELATIVE_RECORD_NUMBER.rl )ANOTE: RELATIVE_RECORD_NUMBER should only be included if the 2 file being accessed is a relative file. 3 RMS_PUTKEY-Function: Writes records using keyed access.CNote: The following routine is used to put records into a fileE using keyed access. For a rel ative file or sequential fileD with fixed length records, the key is the relative recordE number in the file and must be included in the call to theG routine. For indexed files, the key is contained within the record. =Syntax: IOFLAG = RMS_PUTKEY( FILE_ID.rl, RECORD_BUFFER.ab,0 RECORD_SIZE.rw, : RELATIVE_RECORD_NUMBER.rl)GNote: RECORD_SIZE specifies the length of the record in b ytes. YouD need not write a complete record. RELATIVE_RECORD_NUMBERE should not be included in the call for indexed files. You- cannot overwite existing records.  3 RMS_PUTSEQ2Function: Writing a record with sequential access>Syntax: IOFLAG = RMS_PUTSEQ( FILE_ID.rl, RECORD_BUFFER.ab, 6 RECORD_SIZE.rw) 3 RMS_PUTVFC 4Function: Writes variable w/ fixed control records.>Syntax: IOFLAG = RMS_PUTVFC( FILE_ID.rl, RECORD_BUFFER.ab, 0 RECORD_SIZE.rw, 9 RECORD_HEADER_BUFFER.ab, ; RELATIVE_RECORD_NUMBER.rl ) FNOTE: RELATIVE_RECORD_NUMBER should only be included for writing ' records into relative files. ww@k+1 Action_Routines@ Completion routines are only available for position independent subroutines.H It is occasionally useful to have a particular subroutine invokedH based upon the result of a file or record processing routine. RMSH Interface provides two manners of specifying a procedure to execute.H With either method, you make the specification by passing a subroutineH name within a function call to an RMS Interface file or recordH processing subroutine. The two types of function calls available are0 for synchronous and asynchronous processing. 2 SynchronousH For synchronous processing, the function calls are SUC_ (orH SUCCESS_) and ERR_ (or ERROR_). If you specify either of theseH function calls within a call to a file or record processingH subroutine, the procedure you specified within the function call willH be invoked based upon the status code that the RMS system softwareH returns. If you specified a function call to SUC_ and the low orderH bit of the status code is on, then the procedure you passed to SUC_H will be called. Likewise, if you specified a function call to ERR_H and the low order bit of the status code was off, the procedure youH passed to ERR_ will be called. Two parameters are passed to theH procedure that is invoked. The first is the IFI_ associated variableH (by reference) for that file. The second argument is the status codeH (by reference) for that particular I/O that occurred. (If you wantH the RMS status code to be returned to the section of your program thatH originally called the record or file processing routine, you mustH declare the conditionally invoked subroutine as an integer functionH and specify the value of the function to be equal to the value of theH RMS status code passed to it). Thus within the procedure that isH invoked, you may reference any information about the file you desireH by sending the IFI_ variable to RMS_INFO. Note that these functionH calls should ONLY BE SPECIFIED FOR SYNCHRONOUS file and recordH processing (actually the only asynchronous processing that may beH specified is with record processing). If you use asynchronous recordH processing and employ either the SUC_ or ERR_ function calls, theH procedure you pass will be invoked prematurely. Asynchronous recordH processing is specified by using the ROP_ mnemonic 'ASY'. See theB next page for an example of synchronous use of an error routine. 3 Example1 The following example may clarify things a bit.:  ! The following subroutine will execute if there is; ! an error opening a file in the main program below.5 INTEGER FUNCTION OPEN_ERROR( FILE_ID, STATUS ) IMPLICIT INTEGER*4 (A-Z) < ! Use the file information display routine to tell us ! what went wrong.& CALL PRINT_FILE_INFO( FILE_ID ): ! Return the file status value to the main program. OPEN_ERROR = STATUS RETURN ! Main program follows PROGRAM DEM ONSTRATE IMPLICIT INTEGER (A-Z) EXTERNAL OPEN_ERROR ! Try to open two files:D IOFLAG = RMS_OPEN ( FNM_( 'FILE1.DAT' ), ERR_( OPEN_ERROR ),> IFI_( FILE1_ID ), [ etc. ] .... )A ! The above subroutine OPEN_ERROR will have been called ifC ! there was an error opening FILE1.DAT. OPEN_ERROR returned' ! the RMS status code to IOFLAG.@ IF ( .NOT. IOFLAG )THEN [ try to recover for FILE1.DAT ]) ! Now try to op en the second file.D IOFLAG = RMS_OPEN ( FNM_( 'FILE2.DAT' ), ERR_( OPEN_ERROR ),> IFI_( FILE2_ID ), [ etc. ] .... )A ! The above subroutine OPEN_ERROR will have been called ifC ! there was an error opening FILE2.DAT. OPEN_ERROR returned' ! the RMS status code to IOFLAG.@ IF ( .NOT. IOFLAG )THEN [ try to recover for FILE2.DAT ] ... ... 2 Asynchronous H If you are doing asynchronous record processing, then theH function calls in which to pass the conditionally invoked subroutineH are ASYNC_SUC_ (or ASYNC_SUCCESS_) and ASYNC_ERR_ (or ASYNC_ERROR_).H The procedure will be invoked when the RMS system software hasH completed, which may be some time after control has returned to yourH program. The invoked subroutines are different in that they are trulyH asynchronous and are passed an AST argument list. The AST parameterH value in this list specifies the address of the associated (RAB)K control block. Thus, the synchronous example would have blown up if youH had passed OPEN_ERROR within a call to ASYNC_ERR_. If the subroutineH that you call is incapable of asynchronous operation (for example,H RMS_CREATE) or is at the time operating synchronously, then theH ASYNC_xxx_ completion routine you specify will simply be invoked in aH synchronous manner. It will still be passed an AST argument list. InH the case of RMS_CREATE, for example, the argument passed to the4 completion routine will be the address of the FAB.wwk+ 1 RMS_Info8 RMS_INFO -- The RMS Interface5 File Inquiry Subroutine E Function: Provides a simple method of retrieving information aboutB the files you are accessing via the RMS Interface software. " Syntax: CALL RMS_INFO( FILE_ID,: [ 'Mnemonic 1', Target 1 ],?  [ 'Mnemonic 2', Target 2 ], ...) M Explanation: The first argument specified is ALWAYS the IFI_ variableM associated with the file. Following that, all remaining argumentsM come in couplets. The first argument of a couplet is a characterM string that serves as a mnemonic specifying the information you wantM about the file. The second argument in the couplet is the destination= address of where you want the informat ion sent.  M Note that for information about an XABKEY, XABALL, XABRDT, XABDAT, orM XABPRO block, you must explicitly define the block before or whileM invoking either RMS_OPEN, RMS_CREATE, or RMS_DISPLAY. FAB, RAB, NAM,< XABFHC, and XABUM blocks are automatically allocated. 2 FAB_itemsC RMS_INFO specification chart for FAB related itemsG Mnemonic Notes Meaning/File control block Destination specifierG ALQ Allocation quantity/FAB 4 byte integer variableG BKS Bucket size/FAB 4 byte integer variableG BLS Block size/FAB 4 byte integer variableG DEQ Default extension quantity/FAB 4 byte integer variableD DEV 2 Device characteristics/FAB Character descriptorO DEV_M 4 Device characteristics/FAB 4 byte integer variable as maskH DNA 1 Default file name /FAB (byte) array or descrptrD DNM  Default file name/FAB Character descriptorG DNS Default file name size/FAB 4 byte integer variableG FABCTX FAB context field/FAB 4 byte integer variableG FABSTS FAB status field/FAB 4 byte integer variableG FABSTV FAB status value field/FAB 4 byte integer variableD FAC 2 File Access/FAB Character descriptorO FAC_M 4 File Access/FAB 4 byte integer variable as maskH FNA 1 File name /FAB (Byte) array or descrptrD FNM File name/FAB Character descriptorG FNS File name size/FAB 4 byte integer variableD FOP 2 File processing options/FAB Character descriptorO FOP_M 4 File processing options/FAB 4 byte integer variable as maskG FSZ Fixed header size/FAB 4 byte integer variableG GBC Global Buffer count/FAB 4 byte integer variableG MRN Maximum record number/FAB 4 byte integer variableG MRS Maximum record size/FAB 4 byte integer variableD ORG 2 File organization/FAB Character descriptorG ORG_V 3 File organization/FAB 4 byte integer variableD RAT 2 Record Attributes/FAB Character descriptorG RAT_M 4 Record Attributes/FAB 4 byte integer variableD RFM 2 Record format/FAB Charac ter descriptorG RFM_V 3 Record format/FAB 4 byte integer variableG RTV Retrieval window size/FAB 4 byte integer variableD SDC 2 Secondary device Character Descriptor# characteristics/FABG SDC_M 4 Secondary device 4 byte integer variable# characteristics/FABD SHR 2 File sharing/FAB Character descriptorO SHR_M 4 File sharing/FAB 4 by te integer variable as maskG STS FAB status field/FAB 4 byte integer variableG STV FAB status value field/FAB 4 byte integer variable 2 RAB_items A RMS_INFO specification chart for RAB related itemsEMnemonic Notes Meaning/File control block Destination specifierG BKT Bucket code/RAB 4 byte integer variableG KBF Key buffer address/RAB 4 byte integer variableG KRF Key of reference/RAB 4 byte integer variableG KSZ Key size/RAB 4 byte integer variableG MBC Multiblock count/RAB 4 byte integer variableG MBF Multibuffer count/RAB 4 byte integer variableH PBF 1 Prompt buffer contents/RAB (Byte) array or descrptrG PSZ Prompt buffer size/RAB 4 byte integer variableG RABCTX RAB context field/RAB 4 byte integer variableG RABSTS  RAB status field/RAB 4 byte integer variableG RABSTV RAB status value field/RAB 4 byte integer variableG RABS_FAB Address of FAB with which 4 byte integer variable) the RAB is associated/RABD RAC 2 Record Access/RAB Character descriptorG RAC_V 3 Record Access/RAB 4 byte integer variableH RBF 1 Record Buffer contents/RAB (Byte) array or descrptr< RFA Records file add ress/RAB 6 byte arrayD ROP 2 Record processing options/RAB Character descriptorG ROP_M 4 Record processing options/RAB 4 byte integer variableG RSZ Record size/RAB 4 byte integer variableG TMO I/O timeout/RAB 4 byte integer variableH UBF 1 User Buffer contents/RAB (Byte) array or descrptrG USZ User buffer size/RAB 4 byte integer variable 2 NAM_items A RMS_I NFO specification chart for NAM related itemsEMnemonic Notes Meaning/File control block Destination specifierH DEV_A 1 Device name/NAM (Byte) array or descrptrG DEV_L Device name length-bytes/NAM 4 byte integer variableN DID Directory Identification/NAM 3 element 2-byte integer arrayH DIR_A 1 Directory name/NAM (Byte) array or descrptrG DIR_L Directory name length-bytes/NAM 4 byte integer variable= DVI  Device Identification/NAM 16 byte arrayH ESA 1 Expanded string contents/NAM (Byte) array or descrptrG ESL Expanded string length/NAM 4 byte integer variableG ESS Expanded string size/NAM 4 byte integer variableN FID File identification/NAM 3 element 2-byte integer arrayD FNB 2 File name bits mask/NAM Character descriptorO FNB_M 4 File name bits mask/NAM 4 byte integer variable as maskH NAME_A 1 Name of file/NAM (Byte) array or descrptrG NAME_L File name length/NAM 4 byte integer variableH NODE_A 1 Node name/NAM (Byte) array or descrptrG NODE_L Node name length/NAM 4 byte integer variableG RLF Related file NAM block addr/NAM 4 byte integer variableH RSA 1 Resultant string contents/NAM (Byte) array or descrptrG RSL Resultant string length/NAM 4 byte int eger variableG RSS Resultant string size/NAM 4 byte integer variableH TYPE_A 1 File type/NAM (Byte) array or descrptrG TYPE_L File type length/NAM 4 byte integer variableH VER_A 1 File version/NAM (Byte) array or descrptrG VER_L File version length/NAM 4 byte integer variable2 XABKEY_itemsB RMS_INFO specification chart for XABKEY related itemsEMnemonic Notes Meaning/File control block Destination specifierG DAN Data Area Number/XABKEY 4 byte integer variableG DBS Data bucket size/XABKEY 4 byte integer variableG DFL Data Bucket fill size/XABKEY 4 byte integer variableD DTP 2 Key data type/XABKEY Character descriptorG DTP_V 3 Key data type/XABKEY 4 byte integer variableG DVB 1st data bucket block/XABKEY 4 byte integer variableD FLG 2 Key options flag/XABKEY Character descriptorO FLG_M 4 Key options flag/XABKEY 4 byte integer variable as maskG IAN Index area number/XABKEY 4 byte integer variableG IBS Index Bucket size/XABKEY 4 byte integer variableG IFL Index area fill size/XABKEY 4 byte integer variableG LAN Lowest level area number/XABKEY 4 byte integer variableG LVL Level of root bucket/XABKEY 4 byte integer variableG NSG  Number of key segments/XABKEY 4 byte integer variableG NUL Null key value/XABKEY 4 byte integer variableN POS Key position in record/XABKEY 8 element 2 byte integer arrayG PROLOG Prolog version number/XABKEY 4 byte integer variableG REF Key reference number/XABKEY 4 byte integer variableG RVB Root Index bucket block/XABKEY 4 byte integer variableN SIZ Key size/XABKEY 8 element 1-byte i nteger arrayG TKS Total key size/XABKEY 4 byte integer variable3 Prerequisites: If you want info about a particular XABKEY....B Then before issuing the call to RMS_INFO, you must call theB subroutine SETKRF_ (SET Key of ReFerence). This subroutineB expects one argument, that being the reference number of theB XABKEY block from which you want information. The referenceB number is the value that was specified in the REF_ functi on when the key was created.2 XABALL_itemsB RMS_INFO specification chart for XABALL related itemsEMnemonic Notes Meaning/File control block Destination specifierG AID Area ident number/XABALL 4 byte integer variableD ALN 2 Allocation boundary type/XABALL Character descriptorG ALN_V 3 Allocation boundary type/XABALL 4 byte integer variableD AOP 2 Allocation options/XABALL Character descriptorG AOP_M 4 Alloca tion options/XABALL 4 byte integer variableG BKZ Bucket size/XABALL 4 byte integer variableG LOC 1st block of file area/XABALL 4 byte integer variableN RFI Relative file ID/XABALL 3 element 2-byte integer arrayG VOL Relative volume number/XABALL 4 byte integer variableG XABALQ Allocation quantity/XABALL 4 byte integer variableG XABDEQ Default extens quant/XABALL 4 byte integer variable3 Prerequisites : If you want info about a particular XABALL....B Then before issuing the call to RMS_INFO, you must call theB subroutine SETAREA_ (Sets file area number). This subroutineB expects one argument, that being the area number of theB XABALL block from which you want information. The areaB number is the value that was specified in the AID_ function+ when the allocation block was created.2 XABPRO_itemsB RMS_INFO spec ification chart for XABPRO related itemsEMnemonic Notes Meaning/File control block Destination specifierG GRP Group number of owner/XABPRO 4 byte integer variableG MBM Member number of owner/XABPRO 4 byte integer variableG MTACC Mag tape accessibility/XABPRO 4 byte integer variableD PRO File protection/XABPRO Character descriptorO PRO_M File protection/XABPRO 4 byte integer variable as maskG RVN Revision number/XABPRO 4 byte integer variableG UIC GRP/MBM nmbr of owner/XABPRO 4 byte integer variable2 XABDAT_items B RMS_INFO specification chart for XABDAT related itemsEMnemonic Notes Meaning/File control block Destination specifierD BDT 6 Backup date and time/XABDAT Character descriptorB BDT_V 7 Backup date and time/XABDAT 8 bytes (quadword)D CDT 6 Creation date and time/XABDAT Character descriptorB C DT_V 7 Creation date and time/XABDAT 8 bytes (quadword)D EDT 6 Expiration date and time/XABDAT Character descriptorB EDT_V 7 Expiration date and time/XABDAT 8 bytes (quadword)D RDT 6 Revision date and time/XABDAT Character descriptorB RDT_V 7 Revision date and time/XABDAT 8 bytes (quadword)G RVN Revision number/XABDAT 4 byte integer variable2 XABRDT_itemsB RMS_INFO specification chart for XABRDT related itemsEMnem onic Notes Meaning/File control block Destination specifierD RDT_RDT 6 Revision date and time/XABRDT Character descriptorB RDT_RDT_V 7 Revision date and time/XABRDT 8 bytes (quadword)G RDT_RVN Revision number/XABRDT 4 byte integer variable2 XABSUM_items B RMS_INFO specification chart for XABSUM related itemsEMnemonic Notes Meaning/File control block Destination specifierG NOA Number file areas/XABSUM 4 byte integer var iableG NOK Number of keys in file/XABSUM 4 byte integer variableG PVN Prologue version number/XABSUM 4 byte integer variable2 XABFHC_itemsB RMS_INFO specification chart for XABFHC related itemsEMnemonic Notes Meaning/File control block Destination specifierG EBK End of file block/XABFHC 4 byte integer variableG FFB First free byte in EBK/XABFHC 4 byte integer variableG LRL Longest record length/XABF HC 4 byte integer variableG SBN Starting block number/XABFHC 4 byte integer variableG VERLIMIT File version limit/XABFHC 4 byte integer variable2 Miscellaneous_itemsB RMS_INFO specification chart for miscellaneous itemsEMnemonic Notes Meaning/File control block Destination specifierG FAB Address of FAB/FCB 4 byte integer variableG KEY Address of a key block/FCB 4 byte integer variableG NAM  Address of NAM block/FCB 4 byte integer variableG RAB Address of RAB/FCB 4 byte integer variableD RMS_FN Most recent RMS Interface character descriptor% I/O subroutine calledG XABALL Adress of an XABALL/FCB 4 byte integer variableG XABDAT Adress of an XABDAT/FCB 4 byte integer variableG XABFHC Adress of an XABFHC/FCB 4 byte integer variableG XABPRO Adress of an XABPRO/ FCB 4 byte integer variableG XABRDT Adress of an XABRDT/FCB 4 byte integer variableG XABSUM Adress of an XABSUM/FCB 4 byte integer variable2 NOTE_1& NOTE 1B The entity that is described is copied to the array specifiedB as the destination. The destination may also be a scalar orB dynamic character string descriptor. If so, it is paddedB with trailing blanks. The size of the entity to copy isB implicit. For example, if you specify 'UBF', then 'USZ'B bytes of UBF are copied to the destination address youB specify. If you specify 'NAME_A', then 'NAME_L' bytes areB copied. For 'ESA', the size is 'ESL'. For 'RSA', the size is 'RSL'. 2 NOTE_2 & NOTE 2B To the character string destination is copied the asciiB mnenomics associated with the binary value or mask field inB the file control block. For example, if the file was openedB with 'GET,PUT' access, and the mnemonic you specified toB RMS_INFO was 'FAC', then the character string you specifiedB as the destination would receive '' (if it was longB enough to hold it). Trailing bytes in the character stringB are blankfilled. The contents of the character string areB valid for input into the RMS routines, even though theyB contain the delimiters "<" and ">". You may obtain theB equivalent of an "or" operation by concatenating two or more character strings. 2 NOTE_3 & NOTE 3B To the variable you specify as the destination is copied theB actual binary value within the field of the file control6 block, rather than translating it into mnemonics. 2 NOTE_4 & NOTE 4B To the variable you specify as the destination is copied theB actual binary mask wit hin the field of the file control6 block, rather than translating it into mnemonics.2 NOTE_5& NOTE 5B To the destination of 'POS' is copied into 8 successive 2B byte integer cells the offsets of the (up to) 8 key segmentsB in the record. To the destination of 'SIZ' is copied into 8B successive one-byte cells the sizes of the (up to) 8 key segments in the record. 2 NOTE_6 & NOTE 6B To the character string target is copied the ascii conversionB of the absolute or delta date and time from the respective) field in the XABDAT or XABRDT block. 2 NOTE_7 & NOTE 7B To a target that is 8 bytes in length is copied the absoluteB or delta date and time as it is stored withing the respective) field in the XABDAT or XABRDT block. 2 Target_size0 Length of target variablesB You may notice that some fields in various file controlB blocks are less than 4 bytes long, yet require a 4 byteB target. This is because the RMS_INFO routine always zeros atB least 4 bytes of a numerical target before moving theB quantity into the target. This allows you to use defaultB length (ie 4 byte) integers in your program without having toB worry about erasing previous information in the high orderB bits of the integer. Note that values returned that are less; than 4 bytes long are not sign extended to four bytes.2 Alternate_Method: Another method to specify the info you want...B The file INFODEFS.xxx is an include file intended for aB Fortran, Basic, or Pascal program. 'xxx' is 'FOR', 'BAS', orB 'PAS' respectively. In this file are, defined as constants,B the symbolic values of all the above mnemonics. The symbolicB names are specified by prefixing the mnenomic with "RMS__".B (That 's "RMS" followed by two underscores). (Note that theseB constants are also declared in the environment fileB RMSPROCS.PEN for Pascal). If you wish to use symbolic valuesB instead of character string mnemonics, the symbolic valuesB must either be declared as, or default to, 4 byte integer (ifB you are using Basic or Fortran) in size. Thus, the two. examples below are identical in function. 3 Examples Example 1: IMPLICIT INTEGER (A-Z)) CHARACTER*20 RECORD_ACCESS_STRING ... ...6 CALL RMS_INFO( IFI_VARIABLE, 'RABSTS', IOSTAT,/ 'RAC', RECORD_ACCESS_STRING ) Example 2: IMPLICIT INTEGER*4 (A-Z)) CHARACTER*20 RECORD_ACCESS_STRING INCLUDE 'INFODEFS.FOR' ... ...9 CALL RMS_INFO( IFI_VARIABLE, RMS__RABSTS, IOSTAT,2 RMS__RAC, RECORD_ACCESS_STRING )@ ! The values of RMS__RABSTS and RMS__RAC are defined in ' ! the include file INFODEFS.FORwwmNl+1 Misc_routines> Some utility file processing routines are available.2 RMS_PUTERRMSGA Function: Writes the error-code associated message to user./ Syntax: CALL RMS_PUTERRMSG( IOFLAG.rl )( Example: IMPLICIT INTEGER*4 (A-Z)G IOFLAG = RMS_OPEN( IFI_( FID ), FNM_( 'INFO.DAT' ),...' IF ( .NOT. IOFLAG )THEN. CALL RMS_PUTERRMSG( IOFLAG ) STOP ENDIF2 RMS_GETERRMSG= Function: Translates RMS error code into user's buffer.E Syntax: MSG_LEN = RMS_GETERRMSG( IOFLAG.rl, USERS_BUFFER.ab, = USERS_BUFFER_LEN.rw)A Note: Any unused space in USERS_BUFFER is blank filled.9 The message is truncated if it won't fit.2 PRINT_FILE_INFO? Function: Writes to SYS$ERROR a file information display .2 Syntax: CALL PRINT_FILE_INFO( FILE_ID.rl )= Note: FILE_ID is the file associated IFI_ variable. 3 Example7 Example of Output from PRINT_FILE_INFOB Assume the file you are accessing is named INFO.DAT. It isB located in the directory [BIOCHEM.SOFTWARE.LIBRARY]. You haveB just tried to access a record from it that does not exist. The, file information display would look like:B----------- F I L E I N F O R M A T I O N D I S P L A Y ---@ File: INFO.DAT --- DRB0:[BIOCHM.SOFTWARE.LIBRARY]INFO.DAT;> FAB status word = 10001 FAB status valu = 305 %RMS-S-NORMAL, normal successful completion> RAB status word = 182B2 RAB status valu = 0& %RMS-E-RNF, record not found2 Max rec # = 20000 Max rec size = 1402 # of Blocks = 4 Key size = 3D Last IO = File access = @ File type = File options = 8 Record format = Sharing = 5 Record access = Record Options = <>D--------------------------------------------------------------------> The file display should be self explanatory in its contents.wwZl+ 1 Internals2 FCB File Control Block.H The contents of the IFI_ variable for a particular file points toH a 24 byte (6 longword) area of storage. The 6 longwords have the followin g significance:" Longword Contains6 1 Address of RAB for that file( 2 Address of FAB. 3 Address of NAM block? 4 Address of this block (the IFI value). 5 Address of first XAB. 6 Block ID information H A file header characteristics XAB and a summary XAB are implicitlyH allocated for each file. All other XAB's that are wanted m ust beH explicitly allocated by using the appropriate subroutine and/or function calls. 2 IFI7 The IFI_ function in greater detailD Whenever this function is invoked, the contents of theD variable you send it are stored internally. Thus, if you areD going to sequentially invoke a series of subroutine calls forD the same file, you really need only include the IFI_ functionD call in the argument list for the first s ubroutine you9 invoke. Examples of alternate syntax are provided. 3 ExamplesIOFLAG = RMS_CREATE( # IFI_ (FILE_ID), - [ FAB related functions ],- [ RAB related functions ],- [ NAM related functions ],- [ FAB, RAB, or NAM related. free character strings ],< [ KEY_( IFI_(FILE_ID), [ XABKEY function calls ] ) ],? [ XABALL_( IFI_(FILE_ID), [ XABALL function c alls ] ) ],? [ XABPRO_( IFI_(FILE_ID), [ XABPRO function calls ] ) ],? [ XABDAT_( IFI_(FILE_ID), [ XABDAT function calls ] ) ],? [ XABRDT_( IFI_(FILE_ID), [ XABRDT function calls ] ) ], )you can instead say...CALL IFI_(FILE_ID)IOFLAG = RMS_CREATE( - [ FAB related functions ],- [ RAB related functions ],- [ NAM related functions ],- [ FAB, RAB, or NAM related. free character strings ],, [ KEY_( [ XABKEY function calls ] ) ],/ [ XABALL_( [ XABALL function calls ] ) ],/ [ XABPRO_( [ XABPRO function calls ] ) ],/ [ XABRDT_( [ XABRDT function calls ] ) ], ) 2 Multistream_accessH See the example for the subroutine RMS_CONNECT for anH explanation of this. When you "RMS_CLOSEOUT" a file that was usedH with multistream access, the extra RAB's linked to the FAB are notH deallocated. If you need to explicitly deallocate them, use the RMS, interface subroutine DEALLOCATE_INTERNAL:5 CALL DEALLOCATE_INTERNAL( FILE_ID )H Where FILE_ID is the IFI_ variable associated with that RAB. In theH context of the example used in RMS_CONNECT, the IFI_ variable you would use is EXTRA_RAB.H Only record processing subroutines are allowed to be invokedH when using the "stand alone" IFI variable. Thus, in the context ofH the example used in RMS_CONNECT, calling a subroutine such as> RMS_CLOSE using the IFI_ variable EXTRA_RAB is not allowed.H You may pass the "stand alone" IFI variable to RMS_INFO toH obtain any information you want about the file. If you ask forH information about the RAB, it will return info on the stand aloneH RAB. Otherwise, it will behave as though you are passing the main IFI variable. 2 AST_usageD Using RMS Interface from within asynchronous routinesH As long as you are careful not to perform recursive I/O on aH file within an AST, any RMS Interface subroutine can be safelyH invoked from within an AST. (Recursive I/O means performing I/O on aH file that already has active I/O in progress). The following textH explains how this is possible. Assume the following: Within yourH main program you invoke one or more of the RMS Interface positionH independent subroutines.  You have also written a routine thatH executes as an AST. Within this AST you also invoke one or more ofH the RMS Interface position independent subroutines. Your code may beH executing in such a manner that when the position independent routineH in your non-AST code is only partially completed, the AST routineH will be invoked. The RMS interface software maintains a staticH storage area that is used by the position independent subroutines.H Without the correct measures, the possibility exists that this staticH storage may be corrupted under the circumstances just described. InH order to prevent this, AST delivery (from the caller's access mode)H is disabled during brief critical periods of execution of theH position independent subroutines. At no time during actual I/OH operations are AST's disabled. If you are running a time criticalH process that cannot have AST's disabled for even brief periods (briefH meaning less than a couple hundred machine instructions), then youH can override RMS Interface's automatic AST blocking by calling theH subroutine RMS_ALLOW_AST. (No arguments). You are then fullyH responsible for preventing the conflict of use of RMS Interface'sH static storage area as just described. You can re-enable RMSH Interface's automatic AST blocking by calling RMS_AUTO_AST (No arguments).H Note that this is rarely an issue. The ma in concern of the userH is to avoid performing recursive I/O on a file. By using multistreamH access and employing one RAB for non-ast code and another RAB for AST( code, you can eliminate this problem.wwzl+1 Error_Signaling 1 Error SignalingH This being the initial release of RMS Interface, the finalH decision on error handling has not been made. There is some internalH checking for invalid addresses but currently it is very possible toH blow up your program. Otherwise, the RMS Interface software executesH with a "proceed at all costs and simply warn the user" attitude.H Thus, currently mistakes such as using nonsense mnemonics, sendingH useless arguments in the calls to position independent subroutines,H and similar boo-boos are simply signaled with a severity level ofH warning. Following is a table of the RMS interface error messages.5 Note the error prefix is RMSI F (for RMS InterFace) SEVERITY: WARNING LEVEL, Symbol MessageD %rmsif-w-dupdef Redundant RMS field specification detectedG %rmsif-w-nonsarg Nonsense argument detected in subroutine callC %rmsif-w-mnem Unrecognized mnemonic [ string ] detectedD %rmsif-w-badstrng Invalid character string detected--ignoredB %rmsif-w-argnotall Illegal RMS field specification detectedE %rmsif-w-badnum Invalid numeric charac ter string [ string ]J %rmsif-w-badinfid Invalid item spec for RMS_INFO, arg [ number ]E %rmsif-w-badtime Invalid time format [ string ] encounteredA %rmsif-w-nosuchxab XAB [ ident code ] not found -- created SEVERITY: FATAL1 %rmsif-f-fatalerr Fatal error encounteredI %rmsif_f_badifi Invalid Internal File Identifier encountered; -8 val= [the invalid address] 2 dupdef- %rmsif-w-dupdefD This means, for example, that within on call to RMS_FABDEF, you included two calls to FILE_NAME_. 2 nonsarg - %rmsif-w-nonsargD An argument was included in a call to a subroutine usingD position independent arguments that had no significance. ForD example, if you were to say CALL RMS_FABDEF( FNM_('FILE.DAT), JUNKVAR, etc...) 2 mnem , %rmsif-w-mnemD An unrecognized mnemonic (as listed in the message) was encountered. 2 badstring . %rmsif-w-badstrngD A character string was expected and something else was encountered. 2 argnotall . %rmsif-w-argnotallD A position independent argument that was recognized was usedD out of context. For example, trying to define a data type- for a key within a call to RMS_FABDEF.  2 badnum- %rmsif-w-badnumD An invalid numerical character string (as listed in the@ message) was encountered. For example, saying 'MRN=K20'. 2 badinfid . %rmsif-w-badinfidD In a call to RMS_INFO, an argument that supposedly indicatedD what type of information was desired was invalid. TheD position in the argument sequence of the invalid identifier is listed in the message.  2 badtime - %rmsif-w-badtimeD An invalid absolute or delta time specification was encountered. 2 nosuchxab. %rmsif-w-nosuchxabD Information was requested from RMS_INFO about an XAB thatD previously had not been defined. An empty XAB of the correct type was created. 2 badifi - %rmsif-f-badifiD A corrupted IFI_ variable was passed to one of the RMSD interface routines. This is a fatal error, as further6 processing from such a condition is impossible.ww`l+1 Pascal9 Using RMS Interface with PASCALH The following restrictions/solutions have been implemented for" using RMS Interface with Pascal.H 1. The Pascal environment file for the RMS Interface routinesH includes the declaration of all the subroutines and functionH calls, plus the declaration of all the "RMS__xxx" constantsH that may be sent to RMS_INFO. The name of the environmentH file is RMSPROCS.PEN. The name of the file containing theH procedure declarations (which may be useful to look at so youH can tell just how and in what manner you may pass arguments)H is RMSPROCS.PAS. The name name of the file containing theE declarations for the "RMS__xxx" constants is INFODEFS.PAS.H  2. Wherever in the previous pages it is specified that anH argument is to be a (byte) array, if it is declared as aH varying array, it must be passed as array.body to the RMS Interface routines.H 3. Free Character Strings cannot be used from Pascal because ofH the type checking invloved. There is an extra functionH called STR_, which simply uses as its argument a "packedH array of char", which is sent sent via the %STDESCR mechanismH with attributes of [UNSAFE, READONLY]. Any free character9 string may be passed within the STR_ function.H 4. In your Pascal program, you would call the RMS_INFOH subroutine exactly as previously specified for Fortran.H There is an additional entry point in RMS_INFO calledH RMS_INFO_PAS. This is the procedure actually called from aH Pascal program. You specify arguments exactly as describedH in the Fortran examples. The procedure declaration forH RMS_INFO causes all arguments to be sent as characterH descriptors by using the %STDESCR passing mechanism withB attributs of [UNSAFE, LIST], as "packed array of char".H 5. All the subroutines using position independent arguments areH completely compatible with Pascal, as they are sent argumentsH declared as [LIST] Integer. Every argument is passed within/ a predeclared integer function call.H 6. All position dependent record processing subroutines areH completely compatible with Pascal. Buffers (ie arrays) areH passed via the %REF mechanism, declared [UNSAFE], as an arrayH of unsigned bytes. Integer variables are passed via the %REFH mechanism, declared [UNSAFE], as data type Integer. AgainH note that arrays declared as Varying of Char will not work' unless passed as array.body. ww Ɲl+1 Basic7 Using RMS Interface with BASICF The following restrictions/solutions have been implemented for! using RMS Interface with Basic.F 1. All function calls are predefined in the include fileF RMSDEFS.BAS. This file is necessary for initializing theF names of the position independent functions, and must be- %INCLUDED in your Basic source code.F 2. The RMS Interface software expects buffers to be sent byF reference, but Basic by default passes arrays by descriptor.F Therefore, if you wish to use a previously declared array asF an I/O buffer, you must explicitly pass it by reference.F Note that Basic record variables are passed by reference (default mechanism).F 3. Success and/or error routines must be declared as externalF long constants, then must be passed to the appropriate- function call by value (explicitly).F 4. As shown in the upcoming Basic example, the name of the fileF must first be stored in a character string, then the variableF name of the string is passed to (for example) the FNM_ function.F 5. If you pass a character string such that it is to be aF recipient of data, you must first be sure that sufficientF  space is dynamically allocated for the string. One method ofF doing this is to first fill the string with blanks. This) only applies to dynamic strings.F 6. RMS_INFO works exactly the same with Basic as it does withF Fortran. Remember that dynamic strings that are to recieveF data must first have adequate space allocated, and that7 arrays must be explicitly passed by reference.wwtl+ FRANK Introduction Parameters RMS_FABDEF RMS_RABDEF RMS_NAMDEF RMS_KEYDEF RMS_ALLDEF RMS_PRODEF RMS_DATDEF RMS_RDTDEF FILE_ROUTINESRECORD_ROUTINESAction_RoutinesRMS_Info Misc_routines InternalsError_SignalingPascalBasic