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 Ive made reference to Pic-Lans File transfer facilities. This month Im 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 cant 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