HP 3000 Manuals HP 3000 Manuals
Chapter 3 Remote File Access RFA Overview The Remote File Access service (RFA) allows you to access remote files and devices. By using RFA you can, among other things, create, open, read, write, and close a file that resides on a remote HP 3000. Since the remote "file" may be a peripheral device, you can, for example, read from a tape mounted on a remote system or print local data on a remote printer. RFA does not permit nowait (asynchronous) I/O. The Remote File Access facility uses the same MPE XL file system intrinsics as are employed on a local system. The intrinsics are sent to the remote environment and executed there. Your local program can call these intrinsics explicitly or it can use the input/output procedures specific to the language in which the program is written. You can also access a remote file or device interactively. You will find discussions of interactive and programmatic remote file access methods later in this chapter. RFA Compression Remote File Access (RFA) allows for data compression. RFA data compression can provide faster data transfer, especially over a slow link and when the file being remotely accessed has large records with repeated characters. To invoke data compression for the RFA service, specify the keyword, COMP, in the DSLINE command. The COMP keyword compresses both NFT and RFA data associated to the remote environment specified in the DSLINEcommand. For example, issuing the command DSLINE NODE1;COMP allows for compression of all RFA and NFT data to the remote node called NODE1. To terminate data compression to the specified environment, specify the keyword NOCOMP in the DSLINE command. Issuing this command prevents data compression of any new remote files opened as well as prevents data compression of any future NFT data to the environment specified in the DSLINE command. Files opened remotely while compression is in effect for the environment remain in compressed mode even after the DSLINE;NOCOMP command is issued. The same algorithm is used for both RFA and NFT data compression. The same algorithm is also used with DS Services compression: each sequence of up to 64 consecutive repeated characters is compressed to two bytes, and repeated blanks are compressed to one byte. Without RFA compression enabled, the RFA service can transfer up to 29,900 bytes of data at one time. However, due to overhead associated with managing a compressed data transfer, the RFA service with compression enabled can transfer up to a maximum of 29,000 bytes of data at one time between MPE XL-based HP 3000s. For transfers between an MPE XL-based system and an MPE-V based system the maximum amount of compressed data that can be transferred at one time is 14,500 bytes. RFA compression only compresses data transmitted with the FREAD, FREADDIR, FREADBACKWARD, FWRITE, FWRITEDIR and FUDPATE intrinsics. Therefore, RFA compression is not supported with the Remote DataBase Access (RDBA) service. RFA compression is currently only available on 900 Series HP 3000 systems with version B.00.05 of the NS3000/XL Network Services. If you request RFA compression of a file residing on a system that does not support RFA compression (such as systems running NS3000/V software released prior to version A.00.12), RFA completes the request without compressing the RFA data. No error or warning messages are issued in this situation. FILE Command Specifies a formal designator that may be used to represent a remote file or device in a subsequent command or intrinsic. (Also known as a file equation.) Syntax ____________________________________________________________________________ | | | [=* formaldesignator ] | | [=$NEWPASS ] | | [=$OLDPASS ] | | FILE formaldesignator [=$STDIN ] | | [=$STDINX ] | | [=$STDLIST ] | | [= filereference[: nodespec][ ,filedomain]]| | [;DEV=[ [envname]#][device][,outpri][,numcopies]] | | [;VTERM] | | [;ENV=envfile[:nodespec]] | | [;option]... | ____________________________________________________________________________ UseClick here to view figure. Parameters formaldesignator A name in the form file [.group [.account ]][:nodespec ] that can be used to identify the file in a subsequent command or intrinsic call. (For the meaning of nodespec, see the next parameter explanation. MPE XL currently permits this extended formal designator, with a node specification following a colon, in the FILE and RESET commands, and in the FOPEN intrinsic.) If not equated to another file designator, the formaldesignator contains the actual name of a file. A *formaldesignator (with the asterisk) is a "backreference" to a formal designator defined in a previous FILE command. nodespec Either an environment ID (specified in a previous DSLINE or REMOTE command) or $BACK . This node specification may appear in the file's formal designator or as an extension of an actual file reference. If an environment ID appears in a file designation and in the DEV= option, the attempt to open the file (for example, via FOPEN) will result in an error. $BACK indicates that the file resides one "hop" back toward your local system. This is legal only if the FILE command is issued in a remote session created by a REMOTE HELLO. If the systems involved are connected in an NS3000/XL network, then, one hop back always means your local system. The $BACK specification is equivalent to DEV=# (without an environment name). In either case, the file is accessed through the existing session. filereference The actual name of the file in the form: file [ /lockword ][.group [ .account ]]. filedomain The file domain: NEW or OLD or OLDTEMP. envname An unqualified environment ID. The maximum length is 8 alphanumeric characters. A previously defined environment ID is permitted in the DEV= option, but the domain and organization qualifiers are not permitted and the name may not be longer than 8 characters. device The logical device name or number of a device such as a disc, tape, printer, or terminal. Default: DDISC. If the DEV= option appears, it must be followed by at least one parameter (which can be just #). outpri The output priority requested for a spooled device file. This a value between 1 (lowest priority) and 13 (highest priority). numcopies The number of copies requested for a spooled output device file (maximum 127). VTERM Specifies that the Reverse Virtual Terminal service should be employed instead of Remote File Access. This option applies only if the designated device is a remote terminal. VTERM allows a local application program to perform I/O to remote terminals located on systems that support Reverse Virtual Terminal. (See "Reverse Virtual Terminal" in the chapter on "Virtual Terminal" and "Remote Terminal Access: VT vs. RFA" later in this chapter.) envfile A name representing a file containing laser printer environment information, which controls printing output formats. This name may be an actual file reference or a formal file designator (preceded by an asterisk). option Any valid option in the MPE XL FILE command. For further information, see the MPE XL Commands Reference Manual. Description For Remote File Access purposes, the FILE command can be used to specify a formal designator for a remote file or device. You can use this formal designator to reference the remote file in a subsequent command or intrinsic call. If an environment ID is used to indicate the location of the file, it must be specified in a DSLINE or REMOTE command before you can use RFA. $BACK or DEV=# indicates the node one "hop" closer to your local system when the FILE command has been issued in a remote session. (This may be the local system itself.) Precautions When Using $BACK When using the $BACK backreference with RFA, you need to check the fully qualified node names of the machines on each side of the file transfer. If the domain and organization names differ between the two machines, problems may arise with use of $BACK. To prevent a problem when using $BACK for a transfer between two nodes whose domain and organization are different, configure the remote machine (using NMMGR; NM capability required), so that its network directory includes two entries: 1. localnode.localdomain.localorganization, and 2. localnode.remotedomain.remoteorganization. See the example under "Interactive Access" later in this chapter. RESET Command Cancels file equations. Syntax ______________________________________________ | | | RESET {formaldesignator }| | {@ } | ______________________________________________ Use
NOTE To ensure that the formal designator representing a remote file is syntactically correct, you should always call the FPARSE intrinsic within your program. This intrinsic is documented later in this chapter. For further information on MPE XL file system intrinsics, including FOPEN, FPARSE, IOWAIT, and IODONTWAIT, see the MPE XL Intrinsics Reference Manual.
FPARSE Intrinsic Parses a file designator and determines whether it is syntactically correct. Syntax ______________________________________________________ | | | FPARSE (string,result[,items][,vectors])| ______________________________________________________ Parameters string (input) Byte array, by reference. The file designator that is to be parsed. The string can be terminated by any non-alphanumeric character except a slash, period, colon, underscore, or dash (/, ., :, _, -). result (output) Array of two 16-bit integers, by reference. A value indicating the result of the parse, returned in the first 16-bit word. (The second 16 bits are reserved.) If the value is positive, the file string is syntactically correct and the value indicates the type of file reference being made: * 0 = regular formal designator * 1 = back reference (first character is *) * 2 = system file (first character is $) A negative value represents the error code returned. The error messages are listed in the NS3000/XL Error Messages Reference Manual. items (input) Array of 16-bit integers, by reference. An array of item codes representing portions of the file string. The item codes (except for 0) may be included in any order; the same order is followed in the output vectors array. Item code 0 indicates the end of the items array. The item codes have the following definitions: 0 = indicates end of this array 1 = file name 2 = lockword 3 = group name 4 = account name 5 = environment ID Note that an initial $ is considered part of the file name portion, while * is not. vectors (output) Array of 16-bit integers, by reference. Gives offset and length information that indicates the parse of the file string. Each element of the array is a 16-bit integer; each pair of elements corresponds to a portion of the string, in the same order as the items in the items array. The first 16-bit integer of each pair is the byte offset of the item (from the start of the string to the start of the item), and the second 16-bit integer is the item's length in bytes. A zero value (in both 16-bit integers) means that the item is not present in the file string. For the last element of the vectors array, which corresponds to item code 0 in the items array, the second 16-bit integer is the total length of the file string. The first 16-bit integer of this element is zero unless the result parameter indicates that the file is a system file; in that case the value is the file's default designator type as defined for the FOPEN foptions parameter: 0 = non-system filename 1 = $STDLIST 2 = $NEWPASS 3 = $OLDPASS 4 = $STDIN 5 = $STDINX 6 = $NULL In case of a syntax error in the file designator string, the first word of the first 16 bits of the vectors array returns the byte offset of the invalid item in the string. The second 16 bits will be zero. Description The FPARSE intrinsic parses a file designator and indicates whether or not the string is syntactically correct. You can employ this intrinsic to check a formal designator representing a remote file before attempting to open the file via FOPEN. The optional items and vectors arrays enable you to acquire parsing information for the file designator, namely, the length of each item and its position in the string. The possible items are file name, lockword, group name, account name, and environment ID. The environment ID is treated as a single item; it is not parsed into environment name, domain, and organization. Following are examples of the items (input) and vectors (output) arrays. Remember that the order of entries in the vectors array corresponds to the (arbitrary) order of items in the items array. Also, the last pair of entries of the vectors array has a different meaning from that of the other pairs: the second 16 bits gives the total length of the file string, and the first 16 bits gives a system file code when applicable. In the first example the file string is: FILENAME/LOCKWORD.GROUP.ACCOUNT:CASH.ACCTNG.FINANCE. Example 1 --------------------------------------------------------------------------------------------- | | | | Items Array | Vectors Array | | (item code) | (offset, length) | | | | --------------------------------------------------------------------------------------------- | | | | 1 | 0, 8 | | | | --------------------------------------------------------------------------------------------- | | | | 5 | 32, 19 | | | | --------------------------------------------------------------------------------------------- | | | | 3 | 18, 5 | | | | --------------------------------------------------------------------------------------------- | | | | 4 | 24, 7 | | | | --------------------------------------------------------------------------------------------- | | | | 2 | 9, 8 | | | | --------------------------------------------------------------------------------------------- | | | | 0 | 0, 51 | | | | --------------------------------------------------------------------------------------------- In the second example, the file string is *FILENAME:CASH. Example 2 --------------------------------------------------------------------------------------------- | | | | Items Array | Vectors Array | | (item code)| | (offset, length)| | | | | --------------------------------------------------------------------------------------------- | | | | 1 | 1, 8 | | | | --------------------------------------------------------------------------------------------- | | | | 2 | 0, 0 | | | | --------------------------------------------------------------------------------------------- | | | | 3 | 0, 0 | | | | --------------------------------------------------------------------------------------------- | | | | 4 | 0, 0 | | | | --------------------------------------------------------------------------------------------- | | | | 5 | 10, 4 | | | | --------------------------------------------------------------------------------------------- | | | | 0 | 0, 15 | | | | --------------------------------------------------------------------------------------------- In the third example, the file string is$OLDPASS. Example 3 --------------------------------------------------------------------------------------------- | | | | Items Array | Vectors Array | | (item code) | (offset, length) | | | | --------------------------------------------------------------------------------------------- | | | | 1 | 0, 8 | | | | --------------------------------------------------------------------------------------------- | | | | 2 | 0, 0 | | | | --------------------------------------------------------------------------------------------- | | | | 3 | 0, 0 | | | | --------------------------------------------------------------------------------------------- | | | | 4 | 0, 0 | | | | --------------------------------------------------------------------------------------------- | | | | 5 | 0, 0 | | | | --------------------------------------------------------------------------------------------- | | | | 0 | 3, 8 | | | | --------------------------------------------------------------------------------------------- Example RFA Program What follows is a Pascal program that writes some test data to a remote file, reads the data back from the remote file, and sends the received data to a remote printer to be printed. An environment has been established on the remote node. Prior FILE commands have been issued for the formal file designators representing the remote disc file and remote printer. These file equations specify the remote location of the files. $standard_level 'hp3000'$ $uslinit$ {**********************************} {Note: issue file equations such as} { :file remfile=remfile:rodan} { and} { :file remprint;dev=rodan#lp} {before running this program} {**********************************} program rfaprog(remfile,remprint,output); type teststring = packed array [1..72] of char; smallint = -32768..32767; var remfile : text; remprint : text; i : integer; test1 : teststring; test2 : teststring; begin {program rfaprog} {open remote disc file} writeln('Opening remote disc file'); rewrite (remfile); {write test data to remote file} test1: = 'Remote File Access test'; for i: = 1 to 9 do writeln (remfile,test1); {open remote line printer as devicefile} writeln('Opening remote LP file'); reset (remfile); {read each record from remote file, then print each record on remote printer} rewrite (remprint); for i := 1 to 9 do begin readln (remfile,test2); writeln (remprint,test2); {pick up listing on remote line printer and check output} end; end {program rfaprog}. {remote files/devices closed automatically}