(C) Copyright 1990-1998 Modular Software Corporation. All rights reserved. Version 2.0.0.17 - February 28, 1998
Goto: Table of Contents Index Chapter: 1 2 3 4 5 6 7 8 9 10 11 12 13 14
The format of this command is:
PL-STAT {(options}Available options are:
The PL-LOGOFF verb is used to specify which ports are to have the auto-logoff processing. The PL-LOGOFF settings are stored in a data file in the PIC-LAN account, so they do not need to be reset unless the PIC-LAN account is reloaded.
The PL-LOGOFF verb has several forms that allow you to specify all, none, some, or an exclusion of ports. The formats of the verb are:
PL-LOGOFF PL-LOGOFF ALL PL-LOGOFF NONE PL-LOGOFF INCLUDE 2,3,4,5,6 PL-LOGOFF EXCLUDE 5,6,7,8,9Each of these commands can include the options:
The PL-LOGON verb is used to specify which users (by name) are to have auto-logon enabled and to which Pick accounts they are to be logged on. The PL-LOGON verb has the format:
PL-LOGON user=acct,pswd
PL-TERM host_name {{host_port} esc_char} {port_no}"host_port" may be left blank or entered as an asterisk (*) to allow connection to any open port. "esc_char" may be entered to override the default ctrl<Z> character that is used to exit PL-TERM or send a break character. When the PL-TERM command is executed, a message indicating the system logged in to as well as the destination port number and escape character will be displayed. After the PL-TERM program attaches you to another port on another system, any characters you type are sent to the other system and any characters the other system displays will be sent to your terminal. PL-TERM passes-through characters from your terminal to the other system using the network connection as a medium. While in PL-TERM, you have the following optional functions that are activated by typing <ctrl>Z (or the specified "esc_char"):
PL-COPY {DICT} {{source_system}!{source_account}!}source_file source_item_list {(options)} To:{DICT} {dest_system}!{dest_account}!{(dest_file} {dest_item_list}Options supported include:
The syntax for the PLDOS-IMPORT verb is:
PLDOS-IMPORT dsg_name dos_file pick_file pick_item {CONV=a} {OFFSET=n} {LEN=n} {BLOCKLEN=n} {BLOCKATTR=n} {EXT=n}'dsg_name' is the name of the DOS Services Gateway that is used to access the DOS file.
'dos_file' is the name (including extension) of the DOS file that is to be accessed. Due to Pick TCL parsing restrictions, if the DOS pathname contains '\' characters they must either be replaced with / characters or the entire 'dos_file' parameter must be enclosed in double quotes.
'pick_file' is the name of the Pick file that you wish to save the data in.
'pick_item' is the name of the Pick item that you wish to save the data in. If the EXT option is blank and the imported data is larger than the import size limit (which is dependent on the implementation of Pick) the data will be saved in multiple items with the following naming format:
pick_item pick_item!1 pick_item!2 pick_item!3 ... pick_item!nOptional parameters for the PLDOS-IMPORT verb are:
CONV - A string of characters that specify valid conversions to be applied to the data format. If no conversions are specified, DOS control characters (such as segment marks) are 'quoted' and will be stored in Pick as two-character sequences. This scheme allows DOS binary data to be stored in standard Pick items. If you wish more control over storage formats, you can use the following conversions either alone or in combination.
LEN - Normally the entire DOS file is imported. You can specify a length to import only a part of the DOS file.
BLOCKLEN - Normally the Pick item are stored with a maximum size that is determined by the Pick implementation. You can optionally override this maximum item size value.
BLOCKATTR - If you specify this parameter, each save item will contain at most this number of Pick attributes. This option is typically used in conjunction with the 'A' conversion and DOS text files. This option will also remove the extra attribute mark at the end of multi-item transfers.
EXT - If you specify this option, the string that follows will be used to control the multi-item extension naming as the PLDOS-IMPORT function names items. For example, if you specify EXT=R%3 then PLDOS-IMPORT will store items with the following item ids:
pick_item001 pick_item002 pick_item003 ... pick_item0nnExamples:
PLDOS-IMPORT DSG c:/test.txt T.FILE TEST CONV=A MAXATTR=100 EXT=R%3This example will import from the PicLan DOS Services Gateway named DSG. The file c:\test.txt will be imported in it's entirety and saved in the Pick file T.FILE. DOS CRLF sequences will be converted to Pick attribute marks. The items that are saved will have a maximum of 100 attributes each and the items will be saved with the following item ids:
TEST001 TEST002 TEST003 ... TEST0nnThis usage of PLDOS-IMPORT is ideal for processing large DOS text files.
PLDOS-IMPORT DSG c:/test.dat T.FILE TEST2 CONV=X OFFSET=1526 LEN=100This example will import 100 bytes starting at DOS file offset 1526 and store the data in hex in the single item TEST2.
PLDOS-EXPORT dsg_name dos_file pick_file pick_item {CONV=a} {OFFSET=n} {TRUNCATE} {EXT=n}''dsg_name' is the name of the DOS Services Gateway that is used to access the DOS file.
'dos_file' is the name (including extension) of the DOS file that is to be accessed.
'pick_file' is the name of the Pick file that contains the data that you wish to export.
'pick_item' is the name of the Pick item that you wish to export. If the EXT option is blank and the imported data is larger that the import size limit (which is dependent on the implementation of Pick) the data will be exported from multiple items with the following naming format:
pick_item pick_item!1 pick_item!2 pick_item!3 ... pick_item!nIf the item name is specified as '*', then the PLDOS-EXPORT function will either use the active SELECT list or it will SSELECT the Pick file and export all items concatenated together in sorted order.
Optional parameters are:
CONV - A string of characters that specify valid conversions to be applied to the data format. If no conversions are specified, DOS control characters (such as segment marks) are 'quoted' and will be stored in Pick as two-character sequences. This scheme allows DOS binary data to be stored in standard Pick items. If you wish more control over storage formats, you can use the following conversions either alone or in combination.
TRUNCATE - When updating a portion of a file, this option allows you to truncate the file after data is written. This is the default behavior if you are updating a file without the OFFSET parameter.
EXT - If you specify this option, the string that follows will be used to control the multi-item extension naming as the PLDOS-IMPORT function names items. For example, if you specify EXT=R%3 then PLDOS-IMPORT will store items with the following item ids:
pick_item001 pick_item002 pick_item003 ... pick_item0nnExamples:
PLDOS-EXPORT DSG c:/test.txt T.FILE TEST CONV=A EXT=R%3This example will export to the PicLan DOS Services Gateway named DSG. The file c:\test.txt will be created or replaced. Pick attribute marks will be converted to DOS CRLF sequences. The data to be exported is read from the Pick file T.FILE with item ids:
TEST001 TEST002 TEST003 ... TEST0nnThis usage of PLDOS-EXPORT is ideal for creating large DOS text files.
PLDOS-EXPORT DSG c:/test.dat T.FILE TEST2 CONV=X OFFSET=1526This example will export data from the Pick file T.FILE item TEST2. The data will be converted from hex to binary and stored starting at offset 1526 in the DOS file c:\test.dat.
PLDOS-DELETE dsg_name dos_file'dsg_name' is the name of the DOS Services Gateway that is used to access the DOS file.
'dos_file' is the name (including extension) of the DOS file that is to be accessed.
PLDOS-DIR dsg_name file_specificationThe DOS file name may use '/" characters instead of '\" characters (which are not compatible with Pick TCL string processing) or may be entered within quotes.
PicLan printing functions are described in detail in a later chapter.
Remote printing functions are controlled with the following verbs:
The GA-LAN networking system is a component of R91 that allows R91 systems to be networked together. GA-LAN supports features such as remote file access through remote Q-pointers, remote logins, and remote printing. GA-LAN functions operate with R91 systems connected to each other through one or more serial cables connected to standard GA serial ports. PicLan allows these connections to occur over PicLan network connection channels. This provides GA-LAN users with the following benefits:
The PicLan PL-CONNECT verb is used to "connect" one port on one R91 system to a port on another R91 system. This connection, once made, acts just like a very fast serial cable between the systems. In order to use PL-CONNECT, your system licenses must have the Pick to Pick option (all R91 PicLan licenses include this option). The PL-CONNECT command is only issued from one system in order to establish a bi-directional connection. The format of the PL-CONNECT verb.
PL-CONNECT local_port remote_name!remote_portFor example to connect local port 20 to system "ACCT" port 32, you would execute:
PL-CONNECT 20 ACCT!32With this, you can use PL-CONNECT to connect a group of ports to act as GA-LAN connections. There is no actual limit to the number of ports that you can connect between systems, but for GA-LAN use, more than about 5 is probably not necessary and probably does not give any performance benefits.
In order to use PicLan with GA-LAN, you follow the following procedure:
If you are configuring a PicLan / GA-LAN combined environment, you should consider using the following native GA-LAN functions:
CALL PLSUB.STATUS(connection_number, port_number, result, connection_start, no_connections)'connection_number' is a variable that contains the connection channel number that you wish to query. If this parameter is supplies, then 'port_number' will be filled-in with the port that 'owns' that connection. If this field is left blank, then the 'port_number' field will be used to look-up a terminal host channel that is associated with the specified port.
'port_number' is the derived or supplied port associated with the connection.
'result' is a dynamic array containing information about the connection. This information is in the format:
result<1> = connection_number result<2> = port_number result<3> = connection type (see PL-CODES,PLCB-TYPE for descriptions) result<4> = status (hex bits) result<5> = error (hex bits) result<6> = connection class (see PL-CODES,USER-TYPE for descriptions) result<7> = connection user name result<8> = connection port result<9> = inbound character count result<10> = outbound character count result<11> = connection network number (hex) result<12> = connection node number (hex) result<13> = connection socket number (hex)'connection_start' is the actual PLCB handle for the first connection control block. Most PicLan hosts start numbering connections at zero. Some (specifically UpBoard) start numbering connections at higher numbers. If you are trying to relate PLCB handles to connection numbers, you need to subtract this number from the handle in order to obtain the connection number for this function call.
'no_connections' is the number of connections allocated on this PicLan host.
Examples:
Query a particular port about terminal connections:
CONNECTION.NUMBER = '' PORT.NUMBER = 7 CALL PLSUB.STATUS(CONNECTION.NUMBER, PORT.NUMBER, RESULT, '', '') PRINT 'Port 7 is attached to network node id ' : RESULT<12>Query a particular connection number:
CONNECTION.NUMBER = 8 PORT.NUMBER = '' CALL PLSUB.STATUS(CONNECTION.NUMBER, PORT.NUMBER, RESULT, '' , '') PRINT 'Connection 8 is type ' : PRINT OCONV(RESULT<3>,'TPL-CODES,PLCB-TYPE;X;;1') : PRINT ' and is allocated to port ' : RESULT<2> : '.'
The PLSUB.INIT subroutine call is used to cleanup network resource utilization. If you have allocated any connections, opened any remote files, or used other network resources, this call will free them for this process and for this EXECUTE level. It is recommended that you call this function at both the beginning and end of every program that allocates network resources.
CALL PLSUB.INIT
All of the PLSUB.PICK( ) functions rely on a network connection that is stored in a "HANDLE". A single network connection is established between a Pick process and a destination system. That single connection can then be used to query and manipulate a number of remote Pick data files.
The syntax of the PLSUB.PICK subroutine call is:
CALL PLSUB.PICK( ... 'OPEN CONNECTION',HANDLE,'server_name','','','','','',ERR) 'CLOSE CONNECTION',HANDLE,'','','','','','',ERR) 'PICK OPEN',HANDLE,'acct name','file name','','',RES,FILE.HANDLE,ERR) 'PICK CLOSE',HANDLE,FILE.HANDLE,'','','','','',ERR) 'PICK READ',HANDLE,FILE.HANDLE,ITEM.ID,'','',RES,DATA,ERR) 'PICK READV',HANDLE,FILE.HANDLE,ITEM.ID,ATTR.NO,'',RES,DATA,ERR) 'PICK READU',HANDLE,FILE.HANDLE,ITEM.ID,'','',RES,DATA,ERR) 'PICK READVU',HANDLE,FILE.HANDLE,ITEM.ID,ATTR.NO,'',RES,DATA,ERR) 'PICK WRITE',HANDLE,FILE.HANDLE,ITEM.ID,DATA,'',RES,'',ERR) 'PICK WRITEV',HANDLE,FILE.HANDLE,ITEM.ID,ATTR.NO,DATA,'',RES,'',ERR) 'PICK WRITEU',HANDLE,FILE.HANDLE,ITEM.ID,DATA,'',RES,'',ERR) 'PICK WRITEVU',HANDLE,FILE.HANDLE,ITEM.ID,ATTR.NO,DATA,'',RES,'',ERR) 'PICK DELETE',HANDLE,FILE.HANDLE,ITEM.ID,'','',RES,'',ERR) 'PICK RELEASE',HANDLE,FILE.HANDLE,ITEM.ID,'','',RES,'',ERR) 'PICK RELEASE ALL',HANDLE,'','','','',RES,'',ERR) 'PICK SELECT',HANDLE,FILE.HANDLE,'','','',RES,SEL.HANDLE,ERR) 'PICK CLOSE SELECT',HANDLE,SEL.HANDLE,'','','',RES,'',ERR) 'PICK READNEXT',HANDLE,SEL.HANDLE,NO.IDS,'','',RES,DATA,ERR) 'PICK RPC',HANDLE,SUB.NAME,P1,P2,'','','','',ERR)The variables that are used with the PLSUB.PICK( ) subroutine call are:
FILE NOT FOUND INVALID FILE HANDLE INVALID SELECT HANDLE NOT ON FILE LOCKED EOF
The PLSUB.PICK( ) subroutine implements a "client-server" relationship between two, potentially dissimilar, Pick host systems. A number of implementation details can effect the success of linking multiple Pick system together:
Before DSG file access functions can be used, you must first establish a connection with the DOS Services Gateway computer system. You use the following call for this purpose.
DSG.NAME = 'DSG1' CALL PLSUB.DSG('OPEN CONNECTION', PLCB.HANDLE, DSG.NAME, '', '', '', '', '', ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOPThis example will open a connection to the DOS Services Gateway named DSG1. The variable PLCB.HANDLE will contain a string that you use in subsequent calls to PLSUB.DSG. Your application should not change the contents of this string.
Whenever you open a connection to a DOS Services Gateway, you should always close that connection when you finish using it. The PLSUB.INIT call will also close open connections, but it is a good idea to explicitly close every connection that you open.
CALL PLSUB.DSG('CLOSE CONNECTION', PLCB.HANDLE, '', '', '', '', '', '', ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP
The PicLan DOS Services Gateway functions allow you to scan DOS directories. This function directly translates into DOS directory services calls at the DOS Services Gateway.
FILE.SPEC = 'C:\*.*' OPTIONS = 'ND' CALL PLSUB.DSG('DOS DIR', PLCB.HANDLE, FILE.SPEC, OPTIONS, '', '', '', DATA, ERR) I1 = DCOUNT(DATA,AM) FOR I = 1 TO I1 PRINT 'Filename = ' : DATA<I,1> NEXT IThe file specification parameter is any valid DOS file path. You can include DOS wild-card characters.
The options parameter is used to specify which types of files are to be included in the directory. Options are specified as letter in the options variable. Available option letters are:
DATA<n,1> = filename DATA<n,2> = size DATA<n,3> = attributes (NDHS) DATA<n,4> = date (mm/dd/yy) DATA<n,5> = time (hh/mm/ss)
In order to perform DOS file access operations, you must first open the DOS file. When you open the file, you specify read/write access parameters in the same manner that a DOS application would
FILE.SPEC = 'C:\TEST.DAT' RW.MODE = 'R' SH.MODE = '' CALL PLSUB.DSG('DOS OPEN', PLCB.HANDLE, FILE.SPEC, RW.MODE, SH.MODE, '', FILE.HANDLE, LENGTH, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF FILE.HANDLE = '' THEN PRINT 'FILE NOT FOUND' ; STOPIn this example, the DOS file C:\TEST.TXT is opened in exclusive read mode. Note that the DOS Services Gateway does not maintain current directories for user applications, so you should always specify complete path names when accessing DOS file functions.
Available RW.MODE options are:
The LENGTH variable returns the current file length.
You should always close a DOS file when you finish using it. DOS file handles are a limited resources on the DOS Services Gateway system so you should close files that are no longer needed.
CALL PLSUB.DSG('DOS CLOSE', PLCB.HANDLE, FILE.HANDLE, '', '', '', '', '', ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP
When reading from a DOS file, you specify the opened file handle, the offset you wish to read from, the amount of data you wish to read, and the format of the data that you wish returned to you. PicLan DOS Services Gateway functions operate without the concept of a seek operation. All file I/O statements include an offset that must be specified with each operation.
OFFSET = 0 ;* Read from the beginning of the file LENGTH = 1000 ;* Read 1000 DOS characters CONVERSIONS = 'S' ;* String high bits of invalid Pick characters CALL PLSUB.DSG('DOS READ', PLCB.HANDLE, FILE.HANDLE, OFFSET, LENGTH, CONVERSIONS, RESULT, DATA, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'FILE IS NOT OPENED' ; STOP IF DATA = '' THEN PRINT 'END OF FILE' ; STOP PRINT RESULT - OFFSET : ' bytes have been read.'Conversions are specified as single case-sensitive characters:
The data parameter will contain the data that was read from the DOS file. Depending on the conversion operations used, this parameter may not be the same length as the data read. If you wish to interpret each and every DOS file character without limitations, you will need to read the file in hex.
When writing to a DOS file, you specify the opened file handle, the offset you wish to write from, the data you wish to write, and the format of the data. The number of characters that are written is determined by the supplied data string and the conversions that are applied to it.
OFFSET = 0 ;* Write at the beginning of the file DATA = 'TEST DATA ;* The string to write CONVERSIONS = '' CALL PLSUB.DSG('DOS WRITE', PLCB.HANDLE, FILE.HANDLE, OFFSET, CONVERSIONS, DATA, RESULT, '', ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'FILE IS NOT OPENED' ; STOP PRINT RESULT - OFFSET : ' bytes have been written.'The same conversions are available for writing as reading.
The result parameter will return the resultant file offset after the write operation has completed. The result may not be equal to the offset plus the data length if conversions are applied.
You can truncate the length of an opened DOS file.
LENGTH = 1000 CALL PLSUB.DSG('DOS TRUNCATE', PLCB.HANDLE, FILE.HANDLE, LENGTH, '', '', '', RESULT, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'FILE I/O ERROR' ; STOP
You can set DOS file access locks.
OFFSET = 0 LENGTH = 1000 CALL PLSUB.DSG('DOS LOCK', PLCB.HANDLE, FILE.HANDLE, OFFSET, LENGTH, '', '', RESULT, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'FILE I/O ERROR' ; STOP
You can clear DOS file access locks.
OFFSET = 0 LENGTH = 1000 CALL PLSUB.DSG('DOS UNLOCK', PLCB.HANDLE, FILE.HANDLE, OFFSET, LENGTH, '', '', RESULT, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT < 0 THEN PRINT 'FILE I/O ERROR' ; STOP
You can delete a DOS file. In order to delete a DOS file, that file must not be open.
FILE.SPEC = 'C:\TEST.DAT' CALL PLSUB.DSG('DOS DELETE', PLCB.HANDLE, FILE.SPEC, '', '', '', '', RESULT, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'FILE NOT FOUND' ; STOP
You can rename a DOS file. In order to delete a DOS file, that file must not be open.
FILE.SPEC1 = 'C:\TEST.DAT' FILE.SPEC2 = 'C:\TEST2.DAT' CALL PLSUB.DSG('DOS RENAME', PLCB.HANDLE, FILE.SPEC1, FILE.SPEC2, '', '', '', RESULT, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'FILE NOT FOUND' ; STOP
You can create a DOS directory.
DIR.SPEC = 'C:\TEMP' CALL PLSUB.DSG('DOS MD', PLCB.HANDLE, DIR.SPEC, '', '', '', '', RESULT, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'DIRECTORY NOT CREATED' ; STOP
You can delete a DOS directory.
DIR.SPEC = 'C:\TEMP' CALL PLSUB.DSG('DOS RD', PLCB.HANDLE, DIR.SPEC, '', '', '', '', RESULT, ERR) IF ERR # '' THEN PRINT 'ERROR = ' : ERR ; STOP IF RESULT = '' THEN PRINT 'DIRECTORY NOT DELETED' ; STOP
Goto: Table of Contents Index Chapter: 1 2 3 4 5 6 7 8 9 10 11 12 13 14