PicLan Visual Basic Software Developers Kit

July 22, 1996 - Version 2

This document represents the second release of the PicLan / Visual Basic interface library.

The PicLan VB SDK consists of this documentation along with a number of files documented below. These files are targetted for Visual Basic version 4.0 and will run in either 16-bit or 32-bit mode.

The PicLan VB SDK is usable in several modes. For "object oriented" programming a "Plan" class is available (either in-place or through an OLE server) providing access to PicLan functions. For a more traditional approach, a standard function-call based interface is available as well.

The software that is described herein is bound by the PicLan end-user license agreement which was included with your copy of PicLan. In addition, the following disclosures are made:

THIS SOFTWARE IS NOT SOLD, BUT INSTEAD PROVIDED AT NO CHARGE FOR THE BENEFIT OF THIRD-PARTY DEVELOPERS. NO WARRANTY OF ANY KIND IS MADE REGARDING ITS OPERATION. ITS SELECTION AND USE IS ENTIRELY THE RESPONSIBILITY OF THE END-USER.

This software describes the operation of PicLan VB SDK when used in conjunction with PicLan version 2.0.0.0. PicLan versions prior to 2.0.0.0 may not support all functions within PLAN.BAS.

MODULAR SOFTWARE DOES NOT PROVIDE TECHNICAL SUPPORT FOR THIS PROGRAMMING LIBRARY. IF YOU ARE NOT A VISUAL BASIC PROGRAMMER WITH EXPERIENCE INTERFACING WITH THIRD-PARTY LIBRARIES, THEN THIS SDK IS NOT INTENDED FOR YOU.

Reporting bugs

If you discover what you believe is a bug in this software, please report it to Modular Software using one of the following mechanisms:

a) email support@modsoft.com on the internet.

b) fax Modular Software and (949) 831-6860

be sure to include your return email or fax telephone number. Not all bug reports will be individually answered. Try to include as much detailed information about the bug that you are encountering as possible.

Included Files

The following files are included in the PicLan VB SDK

GETIDS.FRM: small form used with PL-COPYW
GETIDS.FRX: small form used with PL-COPYW
GL_CONST.BAS: global constant file used with PL-COPYW
PLAN_DLL.BAS: small basic file that essentially contains nothing other than Sub Main() for building an in-place DLL server
PLAN_VER.BAS: PicLan in-house version control and display file. Used with PL-COPYW.
PLANCLS.CLS: Plan class module
PLANFRM.FRM: Form module used for PicLan timeouts
PLANFRM.FRX: Form module used for PicLan timeouts
PLANLIB.BAS: PicLan interface library as function calls
PL-COPYW.FRM: PL-COPYW main form
PL-COPYW.FRM: PL-COPYW main form
PL-COPYW.VBP: Visual Basic project file for PL-COPYW.EXE. May be used with 16-bit or 32-bit VB 4.0
PL-ST16.EXE: Compiled 16-bit PL-STATW program using in-place class library
PL-ST16.VBP: 16-bit Visual Basic project file for PL-ST16.EXE
PL-ST16D.EXE: Compiled 16-bit PL-STATW program using Plan class via PLVB16.EXE and OLE automation
PL-ST16D.VPB: 16-bit Visual Basic project file for PL-ST16D.EXE
PL-ST32.EXE: Compiled 32-bit PL-STATW program using in-place class library
PL-ST32.VBP: 32-bit Visual Basic project file for PL-ST32.EXE
PL-ST32D.EXE: Compiled 32-bit PL-STATW program using Plan class via PLVB32.DLL as an in-place OLE server
PL-ST32D.VBP: 32-bit Visual Basic project file for PL-ST32D.EXE
PL-STAT.FRM: PL-STAT main form file
PL-STAT.FRX: PL-STAT main form file
PLVB16.EXE: Compiled 16-bit Plan class OLE server EXE
PLVB16.VBP: 16-bit Visual Basic project file for PLVB16.EXE
PLVB32.DLL: Compiled 32-bit Plan class OLE in-place DLL
PLVB32.VBP: 32-bit Visual Basic project file for PLVB32.DLL
PL-VER.FRM: About dialog box for PL-COPYW
PL-VER.FRM: About dialog box for PL-COPYW

Included Example Programs

This version of the PicLan VB SDK includes several sample programs. These programs are based on production PicLan Windows utilities, but minor changes have been made for the SDK to make them easier to understand. The following two programs are included:

PL-STAT

PL-STATW.EXE is included, somewhat modified and renamed PL-STAT.EXE, for both 16-bit and 32-bit compilation under VB 4.0. This version of PL-STATW uses the Plan class to query the network wheras the PicLan production PL-STATW.EXE program is older and uses function calls. Otherwise, this version of PL-STATW and the production code are identical.

PL-COPYW

PL-COPYW.EXE is included. This program is nearly identical to the production PL-COPYW.EXE program with the exception of some PicLan library cleanups since the 2.0.0.0 product release. This program is included in only source format (you must compile it yourself), but can be compiled for either 16-bit or 32-bit use.

Plan Class Library

The PicLan class library interface consists of the following general groupings of elements, along with a number of individual functions. Groups of elements start with a common prefix. These groups are described below:

"Config" elements are used to retrieve PicLan driver configuration information.
"Conn" elements are used to work with raw network connections.
"Conv" elements are used to convert data from one format to another
"Dyn" elements are used to maniplulate Pick style dynamic arrays
"File" elements are used to open and close connection associated with a Pick data file.
"Item" elements are used to read, write, and delete Pick items
"Select" elements are used to open and close SELECT handles. SELECT handles are the equivelent of performing a SELECT statement in Pick BASIC.
"Server" elements are used to query PicLan servers on the network.
"StrArray" elements are used to manipulate "string arrays". String arrays are a data structure peculiar to PicLan where long strings are broken down into VB arrays of strings. These shorted strings are faster to manipulate and have fewer length limitiations when 16-bit code is running.

There are also functions that do not fall into these categories.

General Usage Guidelines

If you are going to use the PicLan class library, you should consider the following points.

If possible, use only a single instance of the class. Declaring multiple classes allocates multiple clients within the PicLan driver. The maximum number of clients is 16, so using multiple instances of the Plan class within a single program is undesireable.
Make sure that you terminate the class. You should either let the class pointer variable fall out of scope, or explicitly set the class variable to "Nothing" when you are done with it. If you simply end your program with an "End" statement, the Plan class cannot clean up after itself.
There is a bug in the 2.0.0.0 32-bit PLAN32.DLL/PLAN32S.EXE driver that prevents connections from being automatically closed when you deallocate a handle. You must close these connections yourself before you exit. This driver bug will be fixed in a future PicLan build.

Plan Class Methods and Properties Reference

This is a list of the public functions in the Plan class.

Function AllocHandle(ByVal plcbs As Integer) As Integer

Allocate a raw connection handle for subsequent use with Conn class Plan functions.

plcbs - The number of connection control blocks that are available with this handle.
result >= 0 - A handle that is used with subsequent Conn...() function calls.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Property Let BusyFlg(ByVal val As Integer)

Sets the value of "busy flag".

val - If true, PicLan will perform DoEvents while waiting for network data. If false, PicLan will not perform DoEvents.

Setting this flag to true can cause reentrancy problems for VB applications that do not expect this. The default is for Plan to not perform DoEvents when waiting for network traffic.

Property Get ClientsCnt(ByVal Idx As Integer) As Integer

Queries the number of PLCBs allocated to a particular PicLan client handle.

Idx - A number from 0 to 15 for which PicLan client you wish to query.
result > 0 - The number of PLCBs allocated to a particular client
result = 0 - This client is not allocated.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

The client control array is loaded the first time that you call the ClientsCnt() or ClientsStart() functions. If you wish to reload the client control array, you should call GetClients()

Property Get ClientsStart(ByVal Idx As Integer) As Integer

Queries the starting PLCB number allocate to a particular PicLan client handle.

Idx - A number from 0 to 15 for which PicLan client you wish to query.
result >= 0 - The starting PLCB number allocated to a particular client.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

The client control array is loaded the first time that you call the ClientsCnt() or ClientsStart() functions. If you wish to reload the client control array, you should call GetClients()

Property Get ConfigDriverTp() As String

Retrieves the type of network driver that PicLan is using.

Property Get ConfigName() As String

Retrieves the user name from the PL-CFG.INI file.

Property Get ConfigNet() As String

Retrieves the IPX network number for this computer system.

Property Get ConfigNode() As String

Retrieves the IPX node address for this computer system.

Property Get ConfigPingTime() As Integer

Retrieves the "Ping Delay" timeout value in milliseconds.

Property Get ConfigSocket() As String

Retrieves the IPX socket number for this computer system.

Property Get ConfigTimeout() As Integer

Retrieves the packet retry timeout value in milliseconds.

Property Get ConfigVersion() As String

Retrieves the PicLan driver version.

Property Get ConfigXOFFTime() As Integer

Retrieves the "Auto XOFF" delay time value in milliseconds.

Sub ConnBreak(ByVal PNo As Integer)

Sends a "break" signal over a network connection.

Pno - A connection handle returned with ConnOpen().

Function ConnClose(ByVal PNo As Integer) As Integer

Closes an open connection and deallocates it's PLCB (PicLan Control Block).

Pno - A connection handle returned from ConnOpen().
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ConnOpen(ByVal handle As Integer, ByVal name As String, ByVal Tp As Integer, ByVal HostPort As Integer, ByVal LocalPort As Integer, ConnPort As Integer) As Integer

Opens a raw network connection.

handle - a returned client handle from AllocHandle().
name - the name of the PicLan server as an upper-case string.
Tp - the type of connection. Specify PLAN_PLCB_TERM_NODE (2) to open terminal connections, or PLAN_PLCB_FILE_NODE (11) to open file transfer connections.
HostPort - the port number that you wish to open. Specify PLAN_OPEN_TERM_WILD (-1) to open the first available port.
LocalPort - the local port number that you wish displayed in the PL-STAT display on the Pick host.
ConnPort - returned containing the actual port number that you were connected to.

This function is intended for use with terminal connections only. If you use this function with file transfer connections, you will have to implement the PicLan file transfer protocols yourself. To make connections using the file transfer library calls, you use the File... and Item... function instead of the Conn... functions.

Function ConnRead(ByVal PNo As Integer, s As String) As Integer

Reads from a raw network connection.

Pno - a connection handle returned from ConnOpen().
s - returned containing data retrieved from the open network connection.
result >=0 - the number of bytes read
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ConnWrite(ByVal PNo As Integer, ByVal s As String) As Integer

Writes to a raw network connection.

Pno - a connection handle returned from ConnOpen().
s - the data to be written.
result >= 0 - the number of bytes actually written.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

ConnWrite() is non-blocking. If you are writing large amounts of data, you will need to call ConnWrite() multiple times.

Function ConnWriteBlock(ByVal PNo As Integer, ByVal s As String) As Integer

This is a blocking version of ConnWrite(...) that will write the entire contents of "s" even if this requires waiting for network traffic.

Pno - a connection handle returned from ConnOpen().
s - the data to be written.
result >= 0 - the number of bytes actually written.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Sub ConnXoff(ByVal PNo As Integer)

This function will flow control a channel preventing terminal output from being generated at the Pick host. The use of ConnXoff() is optional. You can also just stop reading data and the Pick host system will not be adversly effected.

Pno - a connection handle returned from ConnOpen().

Sub ConnXon(ByVal PNo As Integer)

This funcion will restart flow control thus allowing terminal output at the Pick host. It is used to reverse the effects of ConnXoff().

Pno - a connection handle returned from ConnOpen().

Function ConvAMtoCRLF(s As String) As String

Replaces AM characters with CRLF sequences.

s - source string.
result - destination string.

Function ConvCRLFtoAM(s As String, Residual As String) As String

Replaces CRLF sequences with AM characters.

s - source string.
Residual - on entry - an optional CR character from a previous ConvCRLFtoAM() call.
Residual - on exit - null or a CR character indicating that the source string ended with a CR.
result - destination string.

The "Residual" variable is used to allow the ConvCRLFtoAM() function to be used with strings that extend over multiple variables.

Function ConvBinToHex(s As String) As String

Converts binary data into a hex string

s - source string.
result - destination string.

Function ConvHexToBin(s As String, Residual As String) As String

Converts a hex string into binary data

s - source string.
Residual - on entry - an optional hex character from a previous ConvCRLFtoAM() call.
Residual - on exit - a single character of a trailing hex nibble (4 bits).
result - destination string.

The "Residual" variable is used to allow the ConvHexToBin() function to be used with strings that extend over multiple variables.

Function ConvBinToPick(s As String) As String

Converts binary data into Pick storable data

s - source string.
result - destination string.

The following characters are replaced with two character sequences:

0xF0 - 0xF0 0xF0
0xF1 - 0xF0 0x01
0xF9 - 0xF0 0x09
0xFA - 0xF0 0x0A
0xFB - 0xF0 0x0B
0xFF - 0xF0 0xFF

Function ConvPickToBin(s As String, Residual As String) As String

Converts Pick storable data into binary data.

s - source string.
Residual - on entry - an optional character from a previous ConvPickToBin() call.
Residual - on exit - a single character of a trailing quote sequence
result - destination string.

The "Residual" variable is used to allow the ConvPickToBin() function to be used with strings that extend over multiple variables.

The following character sequences are replaced with single characters.

0xF0 0x?n - 0xFn

Function ConvDateToPick(ByVal d As Variant) As String

Converts a VB format date variable into a Pick format date number

d - source VB date variable.
result - destination Pick format date as a string.

Function ConvPickToDate(ByVal s As String) As Variant

Converts a Pick format date number into a VB format date variable.

s - source Pick format date string.
result - destination VB format date variable.

Function ConvStrip(s As String) As String

Converts high order ascii characters into Chr$(127) characters for storage under Pick.

s - source string.
result - destination string.

The following characters are replaced with Chr$(127)

0xF0
0xF1
0xF9
0xFA
0xFB
0xFF

Function Count(s As String, ByVal c As String)

Counts the number of occurances of "c" within "s".

s - string to search in.
c - string to search for.
result - the number of occurances that "c" appears in "s".

This function is the equivelent of the Pick BASIC COUNT(...) statement.

Function DCount(s As String, ByVal c As String)

Counts the number of fields delimited by "c" within "s"

s - string to search in.
c - string to search for.
result - the number of fields delimited by "c" in "s".

This function is the equivelent of the Pick BASIC DCOUNT(...) statement.

Sub DeallocHandle(ByVal handle As Integer)

Returns a handle allocated with AllocHandle() as frees it's resources. Handle resources are automatically freed when the class is destroyed.

Function DynDelete(s As String, ByVal a1 As Long, ByVal a2 As Long, ByVal a3 As Long) As String

Dynamic array DELETE function.

s - source string.
a1 - attribute counter.
a2 - value counter.
a3 - sub-value counter.
result - destination string.

This function is the equivelent of the Pick BASIC DELETE(...) statement.

The 16-bit version of DynDelete uses Integer parameters instead of Long parameters.

Function DynExtract(s As String, ByVal a1 As Long, ByVal a2 As Long, ByVal a3 As Long) As String

Dynamic array EXTRACT function.

s - source string.
a1 - attribute counter.
a2 - value counter.
a3 - sub-value counter.
result - destination string.

This function is the equivelent of the Pick BASIC EXTRACT(...) statement. The EXTRACT statement provides the same functionality as the x<a1,a2,a3> Pick BASIC syntax.

The 16-bit version of DynExtract uses Integer parameters instead of Long parameters.

Function DynReplace(s As String, ByVal a As String, ByVal a1 As Long, ByVal a2 As Long, ByVal a3 As Long) As String

Dynamic array REPLACE function.

s - source string.
a - new element value.
a1 - attribute counter.
a2 - value counter.
a3 - sub-value counter.
result - destination string.

This function is the equivelent of the Pick BASIC REPLACE(...) statement. The REPLACE statement provides the same functionality as the s<a1,a2,a3> = a Pick BASIC syntax.

The 16-bit version of DynReplace uses Integer parameters instead of Long parameters.

Function FileClose(ByVal FNo As Integer) As Integer

Close a Pick file or RPC connection previously opened with FileOpen().

Fno - a file handle returned from FileOpen().
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function FileOpen(ByVal svr As String, ByVal acct As String, ByVal File As String) As Integer

Open a Pick file or RPC connection.

svr - the name of the PicLan host to make a connection with.
acct - the name of the account (or master dictionary) that contains the file. If acct = "RPC" then a Remote Proceedure Call handle is opened instead of a file.
File - the name of the file to open. You can specify the file as "MD" to open the master dictionary, or "DICT file" to open a file dictionary.
result > 0 - a returned file handled used in subsequent Item...() and RPC() calls.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Sub GetClients()

Refreshes the internal contents of the client array. You should call this function to get new data with the ClientsCnt() and ClientsStart() functions.

Function GetServers(name As String) As Integer

Queries the network for active PicLan servers.

name - the name of the server you are looking for or null to retrieve all servers.
result >= 0 - the number of servers found
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

After you call GetServers(), you call the Servers...() functions to retrieve specific information about the servers queried.

Property Let HostCnt(ByVal val As Integer)

Sets the maximum number of Pick host systems that FileOpen() can communicate with.

val - the maximum number of Pick host system that FileOpen() can communicate with.

The default number of Pick host systems is one. If you need to communicate with more than one Pick host system concurrently, you need to set this value higher before calling FileOpen() for the first time.

Function ItemDelete(ByVal FNo As Integer, ByVal ID As String) As Integer

Deletes an item from an open Pick file.

Fno - a file handle returned from FileOpen().
ID - the item ID to delete.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemRead(ByVal FNo As Integer, ByVal ID As String, d As String) As Integer

Reads an item from an open Pick file.

Fno - a file handle returned from FileOpen().
ID - the item ID to read.
d - a string variable to store the item data.
result = PLAN_OK (0) - Item has been read.
result = PLAN_NOT_ON_FILE (1) - Item does not exist.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemReadA(ByVal FNo As Integer, ByVal ID As String, d() As String) As Integer

Reads an item from an open Pick file as an "array string"

Fno - a file handle returned from FileOpen().
ID - the item ID to read.
d() - a array of string variable to store the item data.
result = PLAN_OK (0) - Item has been read.
result = PLAN_NOT_ON_FILE (1) - Item does not exist.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

"array strings" are used with PicLan to allow Visual Basic to read very large strings. With 32-bit versions of VB, array strings can be more efficient for some types of manipulation functions. With 16-bit versions of VB, array strings prevent string overflow problems.

Function ItemReadNext(ByVal SNo As Integer, ByVal cnt As Integer, d As String) As Integer

Performs a Pick BASIC READNEXT series of statements for a select handle opened with SelectOpen().

Sno - a file handle returned from SelectOpen().
cnt - the number of item Ids to return.
d - a string variable to store the returned item ids as a dynamic array of attributes.
result = PLAN_OK (0) - Item ids have been returned.
result = PLAN_EOF (3) - End of list has been encountered. Item ids are still returned.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemReadv(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, d As String) As Integer

Reads an attribute from an open Pick file.

Fno - a file handle returned from FileOpen().
ID - the item ID to read.
attr - the attribute number to read
d - a string variable to store the item data.
result = PLAN_OK (0) - Item has been read.
result = PLAN_NOT_ON_FILE (1) - Item does not exist.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemReadu(ByVal FNo As Integer, ByVal ID As String, d As String) As Integer

Reads an item from an open Pick file setting a Pick lock.

Fno - a file handle returned from FileOpen().
ID - the item ID to read.
d - a string variable to store the item data.
result = PLAN_OK (0) - Item has been read.
result = PLAN_NOT_ON_FILE (1) - Item does not exist.
result = PLAN_LOCKED (2) - Item is already locked.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemReadvu(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, d As String) As Integer

Reads an attribute from an open Pick file setting a Pick lock.

Fno - a file handle returned from FileOpen().
ID - the item ID to read.
attr - the attribute number to read.
d - a string variable to store the item data.
result = PLAN_OK (0) - Item has been read.
result = PLAN_NOT_ON_FILE (1) - Item does not exist.
result = PLAN_LOCKED (2) - Item is already locked.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemRelease(ByVal FNo As Integer, ByVal ID As String) As Integer

Releases a Pick lock for a single item.

Fno - a file handle returned from FileOpen().
ID - the item ID to release the lock for.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemReleaseAll(ByVal FNo As Integer) As Integer

Releases all Pick locks associated with the connection.

Fno - a file handle returned from FileOpen().
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemWrite(ByVal FNo As Integer, ByVal ID As String, ByVal d As String) As Integer

Write an item on an open Pick file.

Fno - a file handle returned from FileOpen().
ID - the item ID to write.
d - the data to write.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemWriteA(ByVal FNo As Integer, ByVal ID As String, d() As String) As Integer

Write an item on an open Pick file using a string array.

Fno - a file handle returned from FileOpen().
ID - the item ID to write.
d() - the data to write as an array of strings.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemWriteu(ByVal FNo As Integer, ByVal ID As String, ByVal d As String) As Integer

Write an item on an open Pick file retaining any previously set lock.

Fno - a file handle returned from FileOpen().
ID - the item ID to write.
d - the data to write.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemWritev(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, ByVal d As String) As Integer

Write an attribute on an open Pick file.

Fno - a file handle returned from FileOpen().
ID - the item ID to write.
attr - the attribute number to write.
d - the data to write.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Function ItemWritevu(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, ByVal d As String) As Integer

Write an attribute on an open Pick file retaining any previously set lock.

Fno - a file handle returned from FileOpen().
ID - the item ID to write.
attr - the attribute number to write.
d - the data to write.
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Property Let LongTimeout(ByVal val As Double)

Sets the long timeout value for PicLan transactions.

val - the amount of time PicLan will wait to timeout network transactions.

Function RPC(ByVal FNo As Integer, ByVal Cmd As String, p1 As String, d As String) As Integer

Calls a Pick BASIC subroutine cataloged on the Pick host system.

Fno - a file handle returned from FileOpen().
Cmd - the name of the subroutine to call.
p1 - the first parameter passed to the subroutine. This value may not contain attribute marks or non Pick compatible characters.
d - the second parameter passed to the subroutine. This value may contain attribute marks, but not non Pick compatible characters.

Function SelectClose(ByVal SNo As Integer) As Integer

Closes a previously opened select handle.

Sno - a select handle returned from SelectOpen().
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Select handles are automatically closed with ItemReadNext() encounters an EOF condition.

Function SelectOpen(ByVal FNo As Integer) As Integer

Open a select handle for a previously opened Pick file.

Fno - a file handle returned from FileOpen().
result < 0 - An error code. Use ErrorStr() to convert PicLan error codes into printable messages.

Opening a select is the equivelent of a Pick BASIC SELECT statement against a file variable.

Property Get ServersCap(ByVal Idx As Integer) As Integer

Queries the capabilities of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - a number representing the capabilities of the queried server.

Property Get ServersImm(ByVal Idx As Integer) As String

Queries the immediate address of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - the immediate node address of the queried server.

Property Get ServersName(ByVal Idx As Integer) As String

Queries the name of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - the name of the queried server.

Property Get ServersNet(ByVal Idx As Integer) As String

Queries the network number of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - the IPX network number of the queried server.

Property Get ServersNode(ByVal Idx As Integer) As String

Queries the node address of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - the node address of the queried server.

Property Get ServersSn(ByVal Idx As Integer) As Long

Queries the PicLan serial number of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - the PicLan software serial number, or zero if the server does not use a PicLan software serial number.

Not all PicLan servers have serial numbers. Some systems, like DOS Services Gateway systems are PicLan servers but do not have a serial number.

Property Get ServersSocket(ByVal Idx As Integer) As String

Queries the socket address of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - the socket address of the queried server.

Property Get ServersVer(ByVal Idx As Integer) As String

Queries the PicLan version number of a PicLan server.

Idx - the server index number from one to the number of servers retrieved with GetServers().
result - the version number of the queried server.

Property Let ShortTimeout(ByVal val As Double)

Sets the short timeout value for PicLan transactions.

val - the amount of time PicLan will wait to timeout network transactions.

Sub StrArrayAMtoCRLF(d() As String)

Converts AM characters to CRLF characters in-place in a string array.

d() - string array to convert.

Sub StrArrayCRLFtoAM(d() As String, Residual As String)

Converts CRLF characters to AM characters in-place in a string array.

d() - string array to convert.
Residual - residual string allowing multiple string arrays to be processed sequentially.

Sub StrArrayBinToHex(d() As String)

Converts binary data to hex data in-place in a string array.

d() - string array to convert.

Sub StrArrayHexToBin(d() As String, Residual As String)

Converts hex data to binary data in-place in a string array.

d() - string array to convert.
Residual - residual string allowing multiple string arrays to be processed sequentially.

Sub StrArrayBinToPick(d() As String)

Converts binary data into Pick compatible data. See ConvBinToPick() for more details.

d() - string array to convert.

Sub StrArrayPickToBin(d() As String, Residual As String)

Converts Pick compatible data into binary data. See ConvPickToBin() for more details.

d() - string array to convert.
Residual - residual string allowing multiple string arrays to be processed sequentially.

Sub StrArrayStrip(d() As String)

Strips non Pick compatible data from a string array and replaces those characters with Chr$(127). See ConvStrip() for more details.

d() - string array to convert.

Function StrArrayLen(d() As String) As Long

Returns the total length of a string array.

d() - string array to measure.
result - the total length of the string array.

Sub StrArrayGet(s() As String, d() As String, ByVal l As Long)

Moves a specified number of characters from one string array to another.

s() - source string array.
d() - destination string array.
l - number of characters to move.

Property Let Timeout(ByVal val As Double)

Sets the standard timeout value for PicLan transactions.

val - the amount of time PicLan will wait to timeout network transactions.

PlanLib Functions

PicLan includes a Visual Basic file called PlanLib.bas that allows Visual Basic applications to access and update files stored on a Pick system. The VB SDK also includes calls that allow you to invoke Pick BASIC subroutines from within your Visual Basic application in the form of a Remote Proceedure Call (RPC). The file access functions are designed to mirror the file I/O commands and other commands available in Pick Basic. Much of this documentation refers back to the original Pick BASIC documentation and attempts to redocument Pick BASIC are not made here. The RPC functions are designed to mimic the CALL @...(...) function provided in Pick BASIC. The PLAN.BAS file also includes low-level functions that allow access to the Pick system at a streams level. These functions are designed for applications that are implementing terminal emulator type functions. These functions are also not documented here. If you wish to use these low-level functions, you will need to refer to the PicLan DOS/Windows Software Development Kit documentation.

These functions are called directly from the Plan class functions. The documentation for the PlanLib functions is still being prepared, so you should refer to the Plan class documentation and the source code for more details.

Public Function PL_AllocPlcb(ByVal handle As Integer, ByVal ibufs As Integer, ByVal obufs As Integer) As Integer

Allocates a PLCB from a pre-allocate PicLan client handle allocated with PL_InitMem().

Public Function PL_AMtoCRLF(s As String) As String

String conversion function to replace AM characters with CRLF sequences.

Public Sub PL_AMtoCRLFA(d() As String)

String array conversion function to replace AM characters with CRLF sequences.

Public Function PL_BinToHex(s As String) As String

String conversion function to convert a binary string into a hex string.

Public Sub PL_BinToHexA(d() As String)

String array conversion function to convert binary strings into hex string.

Public Function PL_BinToPick(s As String) As String

String conversion function to convert a binary string into a Pick compatible string.

Public Sub PL_BinToPickA(d() As String)

String array conversion function to convert binary strings into Pick compatible strings.

Public Sub PL_Break(ByVal PNo As Integer)

Sends a break signal over an open connection.

Public Function PL_Close(ByVal PNo As Integer) As Integer

Closes an open connection. You must repeatedly call this function until it return non-zero.

Public Function PL_CloseFile(ByVal FNo As Integer) As Integer

Closes an open Pick file or RPC connection.

Public Function PL_CloseSelect(ByVal SNo As Integer) As Integer

Closes an open Pick select handle.

Public Sub PL_CopyA(Src() As String, Dst() As String)

Copies an array of strings.

Public Function PL_Count(s As String, ByVal c As String) As Integer

Counts the number of occurances of "c" withing "s". Equivelent to the Pick BASIC COUNT function.

Public Function PL_CRLFtoAM(ByVal s As String) As String

String conversion function that converts CRLF sequences into AM characters.

Public Function PL_CRLFtoAM2(s As String, Residual As String) As String

String conversion function that converts CRLF sequences into AM characters. Residual allows multiple string to be converted even where CRLF sequences are split between strings.

Public Sub PL_CRLFtoAM2A(d() As String, Residual As String)

String array conversion function that converts CRLF sequences into AM characters. Residual allows multiple string arrays to be converted even where CRLF sequences are split between string arrays.

Public Function PL_DateToPick(ByVal d)

Conversion function between Visual Basic date variable and Pick format date number.

Public Function PL_DCount(s As String, ByVal c As String) As Integer

Counts the number of fields in string "s" delimited by string "c". Equivelent to the Pick BASIC DCOUNT function.

Public Sub PL_DeallocPlcb(ByVal PNo)

De-allocates and allocate PicLan Control Block (PLCB) allocated with PL_AllocPlcb(). You should close any connection before deallocating a PLCB.

Public Function PL_Delete(s As String, ByVal a1 As Long, ByVal a2 As Long, ByVal a3 As Long) As String

Dynamic array DELETE function.

Public Function PL_DeleteItem(ByVal FNo As Integer, ByVal ID As String) As Integer

Deletes an item from an open Pick file.

Public Function PL_ErrorStr(ByVal x As Integer) As String

Converts a negative number PicLan error code into a descriptive string.

Public Sub PL_Exit()

Performs exit cleanup processing. Visual Basic applications should call this function during cleanup.

Public Function PL_Extract(s As String, ByVal a1 As Long, ByVal a2 As Long, ByVal a3 As Long) As String

Dynamic array EXTRACT function. The 16-bit version of this functions uses Integer values for a1, a2, and a3.

Public Function PL_FindServers(ByVal PNo As Integer, ByVal ServerName As String) As Integer

Retrieves PicLan servers.

Public Sub PL_GetA(s() As String, d() As String, ByVal l As Long)

Copies l bytes from string array s() to string array d().

Public Sub PL_GetClient(ByVal Idx As Integer, result As PL_CLIENT_STRUCT)

Retrieves information about a single PicLan client on this workstation.

Public Sub PL_GetClientArray(result() As PL_CLIENT_STRUCT)

Retrieves information about all PicLan clients on this workstation.

Public Sub PL_GetConfig(cfg As PL_CONFIG_STRUCT)

Retrieves PicLan driver configuration information.

Public Sub PL_GetServer(ByVal PNo As Integer, ByVal Idx As Integer, res As PL_SERVER_STRUCT)

Retrieves information about a specific Piclan server queried with PL_FindServers().

Public Function PL_GetServerArray(ByVal PNo As Integer, ByVal ServerName As String, PssArray() As PL_SERVER_STRUCT) As Integer

Retrieves information about PicLan servers.

Public Function PL_HexToBin(s As String, Residual As String) As String

String conversion function that converts hex strings into binary strings. Residual allows multiple string to be converted even where hex sequences are split between strings.

Public Sub PL_HexToBinA(d() As String, Residual As String)

String array conversion function that converts hex string array to binary string arrays. Residual allows multiple string arrays to be converted even where hex sequences are split between string arrays.

Public Function PL_Init(ByVal plcbs As Integer, ByVal bufs As Integer) As Integer

PicLan library initialization function. Call this function before using other PicLan functions setup setup global variables and allocate connection control blocks.

Public Function PL_InitMem(ByVal plcbs, ByVal bufs) As Integer

Allocates a raw PicLan handle for use with PicLan PL_Read(), PL_Write, etc. functions.

Public Function PL_LenA(d() As String) As Long

Returns the total length of a string array.

Public Function PL_Open(ByVal PNo As Integer, SrcPSS As PL_SERVER_STRUCT, ByVal Tp As Integer, ByVal HostPort As Integer, ByVal LocalPort As Integer, ResPCS As PL_CONNECT_STRUCT) As Integer

Opens a raw connection to a PicLan host.

Public Function PL_OpenFile(ByVal svr As String, ByVal acct As String, ByVal File As String) As Integer

Opens a Pick data file. If "acct" is specified as "RPC", then an RPC connection is opened to the Pick host.

Public Function PL_OpenSelect(ByVal FNo As Integer) As Integer

Open a Pick select. This is the same as the Pick BASIC SELECT FILE.VAR TO SELECT.VAR statement.

Public Function PL_PickToBin(s As String, Residual As String) As String

String conversion function that replaces quoted Pick sequences with binary characters. Residual allows multiple strings to be converted even where quotes sequences are split between strings.

Public Sub PL_PickToBinA(d() As String, Residual As String)

String array conversion function that replaces quoted Pick sequences with binary characters. Residual allows multiple string arrays to be converted even where quoted sequences are split between string arrays.

Public Function PL_PickToDate(ByVal s As Variant) As Variant

Conversion function between Pick date number and Visual Basic date variable.

Public Function PL_Read(ByVal PNo As Integer, s As String) As Integer

Function to read characters from a raw connection.

Public Function PL_ReadItem(ByVal FNo As Integer, ByVal ID As String, d As String) As Integer

Reads an item from an open Pick file.

Public Function PL_ReadItemA(ByVal FNo As Integer, ByVal ID As String, d() As String) As Integer

Read an item as a string array from an open Pick file.

Public Function PL_ReadNext(ByVal SNo As Integer, ByVal cnt As Integer, d As String) As Integer

Performs one or more sequential READNEXT statement for an open Pick select.

Public Function PL_ReaduItem(ByVal FNo As Integer, ByVal ID As String, d As String) As Integer

Read an item from an open Pick file setting a lock.

Public Function PL_ReadvItem(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, d As String) As Integer

Read an attribute from an open Pick file.

Public Function PL_ReadvuItem(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, d As String) As Integer

Read an attribute from an open Pick file setting a lock.

Public Function PL_Release(ByVal FNo As Integer, ByVal ID As String) As Integer

Release a Pick lock.

Public Function PL_ReleaseAll(ByVal FNo As Integer) As Integer

Release all Pick locks.

Public Function PL_Replace(s As String, ByVal a As String, ByVal a1 As Long, ByVal a2 As Long, ByVal a3 As Long) As String

Dyanmic array REPLACE function. The 16-bit version of this function uses Integer parameters for a1, a2, and a3.

Public Function PL_ReplStr(s As String, ByVal SearchStr As String, ByVal ReplStr As String) As String

String conversion function to replace all occurances of SearchStr with ReplStr.

Public Function PL_RPC(ByVal FNo As Integer, ByVal Cmd As String, p1 As String, d As String) As Integer

Pick RPC (Remote Proceedure Call). The subroutine specified in "Cmd" will be called with parameters "p1" and "d".

Function PL_ScanDelim(s As String, ByVal Delim As String) As String

Scan delimiters returning each field with each call. When the entire string has been scanned, this function will return the delimiter. You must call this function repetively until all delimiters are retrieved. This function is not re-entrant and you can only scan a single string at one time.

Public Function PL_Strip(s As String) As String

String conversion function to replace non Pick compatible characters with Chr$(127).

Public Sub PL_StripA(d() As String)

String array conversion function to replace non Pick compatible characters with Chr$(127).

Public Sub PL_Term()

Terminate subroutine to cleanup PicLan resources. Your application should use PL_Exit which in turn calls PL_Term().

Public Sub PL_TermMem(ByVal handle As Integer)

Function to release a PicLan client handle.

Public Function PL_Write(ByVal PNo As Integer, ByVal s As String) As Integer

Write to a raw PicLan connection. This function is non-blocking and you must repetively call it until your entire string is consumed.

Public Function PL_WriteBlock(ByVal PNo As Integer, s As String) As Integer

Write blocking to a raw PicLan connection. This function will write your entire source string, even if this requires waiting for network traffic.

Public Function PL_WriteItem(ByVal FNo As Integer, ByVal ID As String, ByVal d As String) As Integer

Write an item to an open Pick file.

Public Function PL_WriteItemA(ByVal FNo As Integer, ByVal ID As String, d() As String) As Integer

Write an item with a string array to an open Pick file.

Public Function PL_WriteuItem(ByVal FNo As Integer, ByVal ID As String, ByVal d As String) As Integer

Write an item to an open Pick file preserving the Pick lock.

Public Function PL_WritevItem(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, ByVal d As String) As Integer

Write an attribute to an open Pick file.

Public Function PL_WritevuItem(ByVal FNo As Integer, ByVal ID As String, ByVal attr As Integer, ByVal d As String) As Integer

Write an attribute to an open Pick file preserving the Pick lock.

Public Function PL_ValidateFileHandle(ByVal FNo As Integer) As Integer

Validate a file handle.

Public Function PL_ValidateSelectHandle(ByVal SNo As Integer) As Integer

Validate a select handle.

Public Sub PL_Xoff(ByVal PNo As Integer)

Flow control a raw PicLan connection.

Public Sub PL_Xon(ByVal PNo As Integer)

Un-flow control a raw PicLan connection.

RPC Information

The ability to call remote proceedures on the Pick host is the most powerful aspect of the PicLan VB interface. This allows you to write your own Pick code and invoke it from within Visual Basic. The following function is used to call an RPC:

Function PL_RPC% (ByVal FNo%, ByVal name$, p1$, d$)

Perform a Remote Proceedure Call to the subroutine specified. The specified subroutine on the Pick host will be called with two parameters, the first being one attribute long, and the second being any number of attributes long. The called subroutine must be cataloged and callable within the context of the PicLan SERVER-PROCESS on the Pick host system.

Care should be taken in calling user-written subroutines. If your subroutine crashes, the SERVER-PROCESS will crash and subsequent network requests will be ignored. When you are developing Pick RPC subroutines, you should execute the SERVER-PROCESS on a terminal or network attached port instead of on a background process in order to facilitate debugging.

The remote subroutine executes within the context of the PicLan SERVER-PROCESS. The SERVER-PROCESS usually executes within the login of whatever account the PL-LOAD PicLan driver load program executed within. This is usually either the SYSPROG (or DM for AP systems) or the PIC-LAN account. You user written subroutine should be written and cataloged so that it can run from within either of these accounts.

There are practical limitations as to what type of processing the called subroutine can perform. Primarily, the limitations are based on limitations of the underlying Pick implementation and the fact that the there is only a single PicLan SERVER-PROCESS and while your subroutine is executing, the SERVER-PROCESS is unable to process other requests. For this reason, you should try to avoid performing operations that take more than one or two seconds to execute. This usually precludes using the BASIC EXECUTE statement to perform operations such as Access SSELECT statements. One option around this limitation is for the called subroutine to use a phantom port (on those Pick systems where this is supported). This way the phantom port can execute the lengthly task, and the calling program can periodically check the Pick host to see if the job is finished.

The other major limitation of the called proceedure is preserving variables from call to call. An array of COMMON elements is available to user written RPC subroutines, but you must share this single COMMON area amongst all applications that use RPC calls. The suggested method of using this COMMON area is to use the first element as a dynamic array of attributes that relate to the position within the rest of the common area. A subroutine can then "name" the elements that it uses and use the Pick BASIC LOCATE statement to quickly find an element by name.

Here is an example RPC that can be used to access files:

' This is a Visual Basic code fragment that is used to open and call a Pick
' subroutine.  In actual Visual Basic code, you would probably include the
' PL_Init and PL_OpenFile calls in the main form Load routine and the PL_Term
' call in the main form UnLoad routine.

    Dim res as Integer
    Dim FileHandle as Integer
    Dim P1 as String
    Dim D as String

    Dim p as New Plan

    FileHandle = p.FileOpen("PICK", "RPC", "")
    If FileHandle < 0 Then
        MsgBox "Error opening RPC connection " & p.ErrorStr(FileHandle), vbCritical, "Error!"
        p = Nothing
        End
    EndIf

    P1 = "OPEN" & VM & "DATAFILE" 'Setup Pick file to open'
    D = ""
    res = p.RPC(FileHandle, "RPC$FILEIO", P1, D)
    If res < 0 Then
        MsgBox "Error calling RPC " & p.ErrorStr(res), vbCritical, "Error!"
        p = Nothing
        End
    EndIf
    Debug.Print "P1 = " & P1
    If P1 = "Error" Then
        MsgBox "Error opening remote file", vbCritical, "Error!"
        p = Nothing
        End
    End If

    P1 = "READ" & VM & "34875" 'Setup a Pick Item ID to read
    D = ""
    res = p.RPC(FileHandle, "RPC$FILEIO", P1, D)
    if res < 0 Then
        MsgBox "Error calling RPC  " & p.ErrorStr(res), vbCritical, "Error!"
        p = Nothing
        End
    End
    Debug.Print "P1 = " & P1
    Debug.Print "D = " & D


      SUBROUTINE RPC$FILEIO(P1,P2)
*
* This is the Pick subroutine on the other end of the RPC call.  In order to
* call this subroutine, it must be cataloged in the account(s) that the
* PicLan SERVER-PROCESS runs in (usually SYSPROG/DM and PIC-LAN).
*
      EQUATE AM TO CHAR(254)
*
* The PicLan SERVER-PROCESS leaves the first 500 common variables open for
* user subroutine use.  You should use the first variable as a dynamic array
* of attributes that you will store "names" of the variables in and then use
* the next 499 variables to store actual data that must be preserved from
* call to call (things like file variables for open files).  This system
* will allow you (and other programmers) to write many types of RPC
* subroutines without them conflicting with each other.
*
* In this example, P1 is used as a command parameter with the first value
* indicating the operation (OPEN and READ are supported here), and the
* second value indicating the file name or item id for each function.
*
      COMMON V.LIST
      COMMON VARS(499)
*
* This is an example proceedure of how to find an available slot in the
* common array.  Always tread the V.LIST variable as a dynamic array of
* attributes and VARS as associated variable locations.  Remember to only
* access and manipulate variables in VARS that this routine allocated.
*
      LOCATE("RPC$FILEIO",V.LIST;V.LOC) ELSE
         V.LOC = DCOUNT(V.LIST,AM) + 1
         IF V.LOC > 499 THEN
            P1 = 'ERROR' ;* P1 is used as an error indicator.
            RETURN
         END
         V.LIST<V.LOC> = "RPC$FILEIO"
      END
*
      BEGIN CASE
         CASE P1<1,1> = 'OPEN'
            OPEN P1<1,2> TO VARS(V.LOC) THEN
               P1 = ''
            END ELSE
               P1 = 'FILE NOT FOUND'
            END
         CASE P1<1,1> = 'READ'
            READ P2 FROM VARS(V.LOC) , P1<1,2> THEN
               P1 = ''
            END ELSE
               P1 = 'ITEM NOT FOUND'
            END
      END CASE
*
      RETURN

Note that this example does not perform any errror checking which would be necessary in any production application.