PicLan - Networking for Pick

(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

6: Pick Host Functions

When the PicLan network software is installed and the PL-LOAD function has been executed during the system COLDSTART function, several verbs are available to manipulate and monitor the network. These functions are available from TCL in the PicLan account or may be added to the master dictionaries of other accounts by using the account-update function in the PIC-LAN account maintenance menu.

AP/N
You must EXEC the ABS area that PicLan modes have been loaded into in order to use PicLan commands.
AP/Pro
PicLan is automatically loaded into the system boot ABS area. If you install other software into AP/Pro that uses an ABS area, make sure you install the other package after PicLan is installed so that PicLan's ABS modes are available from all ABS areas.
Pick/64+ SeqPro
PicLan is automatically loaded into the system USER ABS area. You must EXEC the USER.ABS file in order to use PicLan functions.

6.1: Status Displays - PL-STAT

This command is used to display the status of the PicLan network. Included in the display is a listing of all PicLan "servers" on the network as well as the status of all current connections to this PicLan server.

The format of this command is:

    PL-STAT {(options}
Available options are:

PL-STAT driver error statistics are particularly useful in isolating network cabling and workstation problems and in diagnosing PicLan installation problems.

6.2: Auto Logoff - PL-LOGOFF

This verb is used to configure specific ports to auto-logoff whenever a workstation disconnects or a connection is broken due to a network error or workstation reboot. This feature requires the PicLan SERVER-PROCESS background job to be running in order to operate.

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,9
Each of these commands can include the options:

The PicLan auto logoff function operates as cooperative processing between the PicLan driver and the PicLan background process. Whenever the PicLan driver disconnects a PicLan terminal channel, it notifies the PicLan background process which can then execute a standard Pick LOGOFF command to log the Pick process off. This logoff processing take place in a Pick BASIC subroutine called PLSP.EVENT.LOGOFF (PicLan Server Process Event Logoff) whose source code is supplied in the PL.BP file in the PIC-LAN account. You can examine and modify this subroutine as necessary to enhance the PicLan auto logoff support functions.

6.3: Auto Logon - PL-LOGON

This verb is used to configure specific users to auto-logon whenever a new connection is established. This feature requires the PicLan SERVER-PROCESS background job to be running in order to operate.

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
AP/N AP/Pro
PL-LOGON can also accept input as PL-LOGON user,user,pswd,md,pswd for logon by user.
This command can include the options:

The PicLan auto logon function operates as cooperative processing between the PicLan driver and the PicLan background process. Whenever the PicLan driver connects a PicLan terminal channel, it notifies the PicLan background process which can then execute a standard Pick LOGON command to log the Pick process on. This logoff processing take place in a Pick BASIC subroutine called PLSP.EVENT.LOGON (PicLan Server Process Event Logon) whose source code is supplied in the PL.BP file in the PIC-LAN account. You can examine and modify this subroutine as necessary to enhance the PicLan auto logon support functions.

6.4: Remote Logins - PL-TERM

The PL-TERM function is used in PicLan installations with more than one Pick server that is licensed to use the Pick to Pick connectivity functions. PL-TERM is used to allow async or console users to access another Pick system on the network as a terminal user. The format of the PL-TERM command is:

    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"):

Exiting the PL-TERM function does not logoff the port on the destination system, so you should be sure to logoff before breaking the connection.

6.5: Remote Copy - PL-COPY

The PL-COPY function is used to copy items from one Pick system to another Pick system on the network. PL-COPY requires the Pick to Pick licensing option of PicLan. The PL-COPY function has the following syntax:

    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 PL-COPY syntax is designed to be an extension to the system COPY function. In fact, the PL-COPY function can be used to copy items from place to place on the local system if desired. The following features and limitations need to be considered in using PL-COPY:

During the PL-COPY functions operation, the BREAK key is disabled. You can abort a copy by pressing the letter 'X'.

6.6: Kill Connection - PL-KILL

It is possible for a PicLan connection to become "hung" because of a system or program failure on either end of the connection. The PL-KILL verb is used to clear these hung connections. The PL-KILL verb begins by displaying the connection information from PL-STAT and then prompts the user for which connection to kill. If the connection is an inbound terminal session, the session is disconnected but the port is not logged off. If you wish to log the port off, use the system LOGOFF command. If the connection is a file-transfer or outbound terminal session connection, the connection is closed and then the control block for that connection is returned to the available space pool.

6.7: Importing from DOS - PLDOS-IMPORT

The PLDOS-IMPORT verb is used to transfer data from a single DOS file into Pick. This verb is executed from Pick and requires the PicLan DOS Services Gateway.

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!n
Optional 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.

OFFSET - Normally the import will start at DOS file offset zero. You can specify another offset to import only a part of the DOS file.

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_item0nn
Examples:

    PLDOS-IMPORT DSG c:/test.txt T.FILE TEST CONV=A MAXATTR=100 EXT=R%3
This 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
        ...
    TEST0nn
This 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=100
This example will import 100 bytes starting at DOS file offset 1526 and store the data in hex in the single item TEST2.

6.8: Exporting Pick Data - PLDOS-EXPORT verb

The PLDOS-EXPORT verb shares the same general syntax as the PLDOS-IMPORT verb:

    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!n
If 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.

OFFSET - Normally the import will start at DOS file offset zero. You can specify another offset to export only a part of the DOS file. If you specify a file offset, an existing file will be updated in place.

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_item0nn
Examples:

    PLDOS-EXPORT DSG c:/test.txt T.FILE TEST CONV=A EXT=R%3
This 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
         ...
    TEST0nn
This usage of PLDOS-EXPORT is ideal for creating large DOS text files.

    PLDOS-EXPORT DSG c:/test.dat T.FILE TEST2 CONV=X OFFSET=1526
This 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.

6.9: Deleting DOS Data - PLDOS-DELETE verb

The PLDOS-DELETE verb is used to delete DOS files.

    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.

6.10: Viewing DOS Directories - PLDOS-DIR

The PLDOS-DIR function can be used to display a directly list of files visible to a DOS Services Gateway. The Pick host must be licensed to use the DOS Services Gateway to use this function. The format of the PLDOS-DIR function is:

    PLDOS-DIR dsg_name file_specification
The DOS file name may use '/" characters instead of '\" characters (which are not compatible with Pick TCL string processing) or may be entered within quotes.

6.11: Remote Printing

The PicLan software allows print jobs to be printed remotely. Remote printing allows a print job generated on a Pick system to be re-directed to a printer that is connected to another Pick system on the PicLan network or to a printer that is connected to a DOS or Novell workstation that is connected to the PicLan network. This remote printing can occur in one of six manners:

PicLan remote printing requires that the PicLan SERVER-PROCESS background task be executing on the Pick host system

PicLan printing functions are described in detail in a later chapter.

6.11.1: Controlling Remote Printing

All PicLan remote printing functions are controlled with two PicLan verbs that are executed on the Pick host systems. These two verbs, in conjunction with configuration information of the remote print destination, control how print jobs are moved from system to system.

Remote printing functions are controlled with the following verbs:

These verbs are all described in a later chapter.

6.12: Network Maintenance Functions

6.12.1: PL-LOAD

The PL-LOAD program is used to initially load the PicLan network driver software into (or underneath) the Pick Operating System. The PL-LOAD program interprets the data that you entered into the PicLan configuration using PL-CONFIGURE. PL-LOAD is normally executed as a part of the system COLDSTART procedure. You can also execute the PL-LOAD program manually from the PIC-LAN account by typing RUN PL.BP PL-LOAD. You cannot execute the PL-LOAD program more than once without re-booting your system and doing so will display an error message and will disable most PicLan functions.

6.12.2: PL-START-SERVER

The PL-START-SERVER verb can be used to manually start the PicLan server process on the configured port. This program operates by executing the LOGON command to start the server process on the desired port. The PL-START-SERVER verb is implicitly executed by the PL-LOAD program if a server port is configured.

6.12.3: PL-STOP-SERVER

The PL-STOP-SERVER verb is used to log the PicLan SERVER-PROCESS program off. Use this verb if you need to perform an orderly system shutdown.

6.12.4: PL-CONFIGURE

The PL-CONFIGURE program is used to enter the PicLan server configuration information. This program may be executed from TCL in the PIC-LAN account or may be executed by selecting the configure menu selection from the PIC-LAN account menu.

6.12.5: Pick to Pick Port Connections - PL-CONNECT verb

PicLan includes a new function that allows one Pick system to communicate with another Pick system over port to port connections via PicLan. This function was implemented specifically to support GA-LAN connections, but other uses with other platforms are possible.

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:

R91 version 8.2 is scheduled to include native ArcNET support for GA-LAN. This support uses a proprietary GA-LAN ArcNET protocol that is not "routable" by IPX or other industry-standard methods. Also, you cannot use the version 8.2 ArcNET driver and PicLan with the same GA network adapter. Testing indicates that PicLan GA-LAN connections and 8.2 native ArcNET connections operate at roughly the same speed.

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_port
For example to connect local port 20 to system "ACCT" port 32, you would execute:

    PL-CONNECT 20 ACCT!32
With 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:

At the present time, the only way to break a connection is to use the PL-KILL command.

If you are configuring a PicLan / GA-LAN combined environment, you should consider using the following native GA-LAN functions:

You will probably want to use the following PicLan Pick to Pick function instead of GA-LAN functions for improved performance.

6.13: Pick Programming Utilities

PicLan includes a number of utilities that allow Pick BASIC program to access network functions. These BASIC functions are subject to revision from time to time so you may wish to consider using them only within utility functions within your application to make it easier to upgrade to future releases of PicLan.

6.13.1: PLSUB.STATUS( )

$IPLSUB.STATUS( )This BASIC subroutine can be used to retrieve status information about a port or a connection. The format of the command is:

    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> : '.'

6.13.2: PLSUB.INIT

$IPLUSB.INIT( )A number of PicLan functions allocate "network resources". The most obvious example of a network resource is a network connection from one system to another. Network resources are not endless and there is a finite number of available connections for each type of Pick host. If you write an application that uses network connections, be sure to return any connections back to PicLan with the appropriate call.

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

6.13.3: PLSUB.PICK( )

$IPLSUB.PICK( )PicLan support remote file access and update functions between Pick host system with the Pick to Pick license option. These remote access functions are implemented with the PLSUB.PICK subroutine. This single subroutine performs a number of distinct function depending on the parameters that are specified.

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
PLSUB.PICK( ) Implementation Details

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:

R83
Pick R83 is a limited item size and limited workspace size Pick implementation and transferring large items (anything over about 15K) may not work and may crash the PicLan SERVER-PROCESS or PLSUB.PICK( ) subroutine with out of workspace errors. Using a Pick "workspace extender" product should help increase the limits.

6.13.4: PLSUB.DSG( )

$IPLSUB.DSG( )This subroutine is used to communicate with a PicLan DOS Services Gateway DOS file access functions. With this subroutine, a Pick application can open, read, write, set locks, and otherwise access the DOS file system that is visible to a PicLan DOS Services Gateway. Use of this function assumes an understanding of DOS file I/O fundamentals.

Establishing a DSG Connection

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 ; STOP
This 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.

Closing a DSG Connection

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
Scanning a DOS Directory

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 I
The 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:

The resulting data variable contains one attribute for each directory entry returned

    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)
Opening a DOS File

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' ; STOP
In 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:

Available file sharing options are:

The result of this operation is a FILE.HANDLE variable and a DATA variable. The FILE.HANDLE variable is a number that refers to the open file and is used in subsequent PLSUB.DSG( ) calls. If the file handle is less than zero the file open failed.

The LENGTH variable returns the current file length.

Closing a DOS File

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
Reading from a DOS File

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 result parameter will return the resultant file offset after the read operation has completed. The result may not be equal to the offset plus the length if an end of file is encountered.

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.

Writing to a DOS File

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.

Truncating a DOS File

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
Setting File Locks

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
Clearing File Locks

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
Deleting a DOS File

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
Renaming a DOS File

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
Creating a DOS Directory

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
Deleting a DOS Directory

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