TITLE:Pic-Lan File Transfer

ISSUE:Multi-value Solutions May '98

AUTHOR:Nathan Rector

COMPANY:Natec Systems

EMAIL:nater@northcoast.com

HTTP:www.northcoast.com/~nater/

In many of my previous articles I’ve made reference to Pic-Lan’s File transfer facilities. This month I’m going to cover the use of these routines.

Pic-Lan can be found on almost all of the native Multi-value platforms. This gives Multi-value OS the ability to read and write DOS/Windows files with ease when normally this ability is close to impossible and/or time consuming.

To use the file transfer programs, the Pic-Lan DOS Service Gateway must be active on the network. The DOS Service Gateway can run on any Windows 95/NT machine without requiring a dedicated box. If you are using the DOS version of the DOS Service Gateway, then you have to have a dedicated box. Even though the Windows version does not require a separate box, I would recommend giving the program as much resource as you can. So run it on a Server or on a computer that is not used often.

Pic-Lan supplies two different programs for file transfer. One is PLSUB.PICK. This program allows you to read and write between different multi-value hosts on the same network regardless of which type of operating system they are running on. However, PLSUB.PICK has nothing to do with DOS files

The other program is PLSUB.DOS. It allows you to manipulate DOS/Windows files. This program has several options that you must assign to each function to work.

There is a setup program that is recommended that you run before each connection is made. This program is PLSUB.INIT. There are no options:

CALL PLSUB.INIT

It is also recommended that PLSUB.INIT be called after closing the connection. It cleans up any outstanding links and resources which may cause problems with future file transfer connections.

Before you can open, read, or write to a DOS/Windows file, you must create a connection to the DOS Service Gateway:

CALL PLSUB.DOS("OPEN CONNECTION",PLCB.HANDLE,DSG.NAME,"","","","","",ERR)

IF NOT(ERR = "") THEN CRT "CRITICAL ERR= ": ERR ; STOP

When you are done with the connection you must close the connection:

CALL PLSUB.DOS("CLOSE CONNECTION",PLCB.HANDLE,"","","","","","",ERR)

IF NOT(ERR = "") THEN CRT "CRITICAL ERR= ": ERR ; STOP

Notice in each case, the program returns the variable ERR. If there is a value in ERR something critical has gone wrong with the connection. This could be a network error or some other error. For example, if the programs can’t find the DOS Service Gateway, then an error "DOS Service Gateway not found" displays. This variable is found in all the file transfer calls. Be sure you create error checking using the variable.

If you are running the DOS Service gateway on a machine that is not dedicated to its use, then you will find that every once in a while, the DOS Service Gateway is not found. This is especially if the machine with the DOS Service Gateway running on it is loading a program or doing some intensive process like calculating a large Excel Spreadsheet. Always check for this and reprocess the command or your programs using these routines will prematurely process your error routines.

...

010 TRIES = 0

011 100*

012 DSG.NAME = "DSG1"

013 CALL PLSUB.DOS("OPEN CONNECTION", PLCB.HANDLE,DSG.NAME,"","","","","",ERR)

014 IF INDEX(ERR ‘CU’,"NOT FOUND",1) AND TRIES

< 3 THEN

015 TRIES = TRIES + 1

016 GOTO 100

017 END ELSE

018 CRT "ERROR= ": ERR

019 STOP

020 END

...

To read or write to a DOS/Windows file, you must first open the file. The format for opening the file is:

CALL PLSUB.DOS("OPEN FILE",PLCB.HANDLE, FILE.LOC,RW.MODE,SHARE.MODE,"",FILE.HANDLE,LENGTH,ERR)

PLCB.HANDLE = is supplied from the Open connection

FILE.LOC = is the DOS file name and directory location. I.e:c:\temp\template.txt

RW.MODE = This tells DOS/Windows how you are accessing the file:

‘R’ = read only. The file must exist first.

‘W’ = write only. The file is overwritten if it exists.

‘RW’ = allows you to read and write to the file. The file is created if it does not exist.

SHARE.MODE = tells DOS/Windows how to lock the file

‘’ = file locked. This file cannot be accessed by others until it is closed by the person who locked it.

‘R’ = allows the file to be read only until it is closed.

‘RW’ = allows other users to read and write to it even though you have it open. In essence, the file is not locked.

FILE.HANDLER = this is used when using the Read and Write options

LENGTH = the total length in characters of this file.

When you are done working with the file you must close the file. The file does not close automatically when the program is terminated like in regular multi-value Basic. If PLSUB.INIT is run before exiting the program, all open files opened are closed. This is not the recommended way to close files because this program does a forced closed, not a controlled close.

To close a file, the format is:

CALL PLSUB.DOS("CLOSE FILE",PLCB.HANDLE, FILE.HANDLE,"","","","","",ERR)

Once you have the file opened you can either read or write to it. When reading from a DOS/Windows file, you can read the whole record, or just blocks of it at a time. This is handy if you are working with DOS/Windows files that are saved in the "Random Access" format.

You can also cause all the CRLF (Carrage Returns/Line Feed) to be converted to AM marks using the option of an ‘a’ (case sensitive). You can also do the reverse when writing to the file by using the option ‘A’ (case sensitive).

The format for writing to a file is:

CALL PLSUB.DOS("DOS READ",PLCB.HANDLE, FILE.HANDLE,OFFSET,LENGTH,OPTION,RESULT,DATA,ERR)

OFFSET = which character to start reading the information from. If you are reading the whole DOS/Windows file then this should be a ‘0’.

LENGTH = the number of characters to read. If you are reading the whole DOS/Windows file, then this should be the same as the LENGTH from the OPEN statement.

OPTION = ‘A’ - converts AM to CRLF

‘a’ - converts CRLF to AM

RESULT = returns the OFFSET plus the number of characters read. This may not be the same as OFFSET + LENGTH if the end of the file was less than the LENGTH. If RESULT is null, then there was nothing to read.

DATA = returns the actual data read

OFFSET = 0

OPTION = "a"

CALL PLSUB.DOS("DOS READ",PLCB.HANDLE, FILE.HANDLE,OFFSET,LENGTH,OPTION,RESULT,DATA,ERR)

IF ERR # "" THEN CRT ERR ; STOP

IF RESULT = "" THEN CRT "File not found" ; STOP

IF DATA = "" THEN CRT "END OF FILE" ; STOP

It is just as easy to write to a DOS/Windows file. The format is:

CALL PLSUB.DOS("DOS WRITE",PLCB.HANDLE, FILE.HANDLE,OFFSET,OPTION,DATA,RESULT,"",ERR)

RESULT = returns the OFFSET plus the number of characters in DATA. If RESULT is null, then the file was not found.

The program that follows is an example of code that uses Pic-Lan to open, manipulate, and write a DOS/Windows file. It shows that the complete process for read and writing to a DOS/Windows file is really quick and easy when working Pic-Lan.

PICLAN.SAMPLE

001 * PICLAN.SAMPLE

002 *

003 * Created By Nathan Rector

004 * Natec Systems

005 *

006 * This is sample program to show how to use the piclan Dos

007 * file transfer functions

008 *

009 CALL PLSUB.INIT ;* as per manual

010 *

011 TRIES = 0

012 100*

013 CALL PLSUB.DSG("OPEN CONNECTION",PLCB.HANDLE,DSG.NAME,"","","","","",E

RR)

014 BEGIN CASE

015 CASE INDEX(ERR 'CU',"PICLAN SERVER NOT FOUND",1) AND NOT(ERR = "")

016 * server was not found. Keep trying

017 RQM

018 GOTO 100

019 CASE TRIES < 3 AND ERR # ""

020 TRIES = TRIES + 1

021 GOTO 100

022 CASE ERR # ""

023 GOTO 900

024 END CASE

025 *

026 RW.MODE = "R" ; SH.MODE = "R" ; TRIES = 0

027 200*

028 CALL PLSUB.DSG("DOS OPEN",PLCB.HANDLE,FILE.SPEC,RW.MODE,SH.MODE,"",FIL

E.HANDLE,LENGTH,ERR)

029 BEGIN CASE

030 CASE INDEX(ERR 'CU',"PICLAN SERVER NOT FOUND",1) AND NOT(ERR = "")

031 * server was not found. Keep trying

032 RQM

033 GOTO 200

034 CASE TRIES < 3 AND ERR # ""

035 TRIES = TRIES + 1

036 GOTO 200

037 CASE ERR # ""

038 GOTO 900

039 CASE FILE.HANDLE = ""

040 GOTO 900

041 END CASE

042 *

043 *** Reads file

044 *

045 OFFSET = 0 ; CONVERSIONS = "a" ; TRIES = 0

046 300*

047 CALL PLSUB.DSG("DOS READ",PLCB.HANDLE,FILE.HANDLE,OFFSET,LENGTH,CONVER

SIONS,RESULT,DATA,ERR)

048 BEGIN CASE

049 CASE INDEX(ERR 'CU',"PICLAN SERVER NOT FOUND",1) AND NOT(ERR = "")

050 * server was not found. Keep trying

051 RQM

052 GOTO 300

053 CASE TRIES < 3 AND READ.ERR # ""

054 TRIES = TRIES + 1

055 GOTO 300

056 END CASE

057 *

058 BEGIN CASE

059 CASE ERR # "" ; GOTO 900

060 CASE DATA = "" ;* blank file

061 CASE RESULT = "" ; GOTO 900

062 END CASE

063 *

064 *** Updates item

065 *

066 DATA<1> = "TESTING PIC-LAN FILE TRANSFER"

067 DATA<2> = " "

068 DATA<3> = "This program does:

069 DATA<4> = "1) open"

070 DATA<5> = "2) Read"

071 DATA<6> = "3) write"

072 *

073 TRIES = 0

074 400*

075 CONVERSIONS = "A"

076 CALL PLSUB.DSG("DOS WRITE",PLCB.HANDLE,FILE.HANDLE,OFFSET,CONVERSIONS,

DATA,RESULT,"",ERR)

077 BEGIN CASE

078 CASE INDEX(ERR 'CU',"PICLAN SERVER NOT FOUND",1) AND NOT(ERR = "")

079 * server was not found. Keep trying

080 RQM

081 GOTO 400

082 CASE TRIES < 3 AND ERR # ""

083 TRIES = TRIES + 1

084 GOTO 400

085 CASE ERR # ""

086 GOTO 900

087 END CASE

088 *

089 TRIES = 0

090 800*

091 CALL PLSUB.DSG("DOS CLOSE",PLCB.HANDLE,FILE.HANDLE,"","","","","",ERR)

092 IF INDEX(ERR 'CU',"PICLAN SERVER NOT FOUND",1) AND NOT(ERR = "") THEN

093 * server was not found. Keep trying

094 RQM

095 GOTO 800

096 END

097 *

098 900*

099 CALL PLSUB.DSG("CLOSE CONNECTION",PLCB.HANDLE,"","","","","","",ERR)

100 *

101 CALL PLSUB.INIT ;* as per manual

102 END