Chapter 5. The Peer-to-Peer Client/Server (PPCS) Component

Chapter 5. The Peer-to-Peer Client/Server (PPCS) Component
	Part II. C-Language Components

Description

Objects of type ppcstype1 are a base from which data available from some PPCS server can be accessed. Each object of type ppcstype1 uses one communication medium such as UDP or a serial port.

Type Tags

None

Object Value

Objects of type ppcstype1 have no value, and it is an error to try to get or set this value.

ppcstype1.new()

Description

Creates a new ppcstype1 object and specifies the nature of the comunication method it will use. Parameters must be specified for exactly one of the possible media.

Prototype

ppcstype1.new ( integer udpport, integer serialport, integer baudrate, integer parity, integer stopbits, integer error, string username )

Parameters

Parameter	Default value	Type name	Description
udpport	None	integer	The UDP port number to use for the new ppcstype1 object. If this is specified then no parameters for other communication media should be given. If `udpport` is assigned the value `.nul` then a random port will be assigned.
serialport	None	integer	The serial port to use for the new ppcstype1 object. If this is specified then no parameters for other communication media should be given.
baudrate	19200	integer	The baud rate to use if the new ppcstype1 object is to use serial communications.
parity	0	integer	The parity to use for serial communications. Permitted values are: 0 (no parity), 1 (odd parity) and 2 (even parity).
stopbits	1	integer	The number of stop bits to use in serial communications. Permitted values are 1 and 2.
error	`.nul`	integer	Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If `error` is not specified or is `.nul` then any error that occurs during object creation will halt the program. If an error object is specified and an error occurs during execution then the error code is output into that object and the method returns `.nul`.
username	platform dependent	string	The username must be at least one character in length and cannot be greater than eighteen characters in length. The username for a ppcstype1 object is the username used for all operations performed on files opened using the ppcstype1 object.

Properties

Property	Type	Description
_	type(*)	This property is provided for use by the user to attach any object of any type to the type in which this property is provided.
__	type(*)	This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property.
parity	integer	Contains the parity setting being used, if the object uses serial communications, or `.nul` if not.
serialport	integer	Contains the number of the serial port in use, if the object uses communications, or `.nul` if not.
stopbits	integer	Contains the number of stop bits being used, if the object uses serial communications, or `.nul` if not.
type	type	Specifies the ppcstype1 type object.
udpport	integer	Contains the UDP port number if the object uses UDP, or `.nul` if not.
username	string	Contains the username for all PPCS operations performed using the `ppcstype1` object.

Methods

gettablenames()

Description

Gets the names of the PPCS files which are available on a specified PPCS server. If the attempt to get the table names is successful then .nul is returned. If the attempt is not successful and neither the error nor errortext parameters are provided then an error is raised. If the attempt is not successful and at least one of the error or errortext parameters are provided then .nul is returned and error information is output in the error or errortext objects provided.

Prototype

ppcstype1var.gettablenames ( string address, array tablenames, string pattern, integer codepage, integer error, string errortext, integer retry, integer timeout )

Parameters

Parameter	Default value	Type name	Description
address	None	string	The internet address, machine name or IP address and port number of the PPCS server providing the file names to be retrieved.
tablenames	None	array	Specifies an object of type array which is used to output the names of the files which are available from the specified server and which match the specified pattern, if any. The first table name, if any, is placed in the array in the position '[1]', the second in position '[2]', and so on. The number of table names retrieved in placed in position '[]'.
pattern	""	string	A pattern used to restrict the table names which will be retrieved. Only names which match the pattern will be output. The matching of a name to a pattern follows the rules for the intrinsic function `.like1`.
codepage	850	integer	The number of the OEM codepage that will be assumed to be in use by the PPCS server providing the file.
error	`.nul`	integer	Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If `error` is not specified or is `.nul` and `errortext` is not specified or is `.nul` then any error that occurs during name retrieval will halt the program. If an error object or errortext object is specified and an error occurs during execution then the error code or text is output into that object and the method returns `.nul`.
errortext	`.nul`	string	Specifies an object that is used to output any error text generated during the execution of the method. This parameter must be an object, not a string value. If `error` is not specified or is `.nul` and `errortext` is not specified or is `.nul` then any error that occurs during name retrieval will halt the program. If an error object or errortext object is specified and an error occurs during execution then the error code or text is output into that object and the method returns `.nul`.
retry	1000000	integer	The number of microseconds between retries, if the operation is not successful immediately.
timeout	5000000	integer	The number of microseconds allowed for the operation to complete before it is assumed that it will fail.

openudpfile()

Description

Opens a database file on a PPCS server using UDP. The ppcstype1 object for which the method is called must be using UDP. If the attempt to open the file is successful then a reference to an object of type ppcstype1file is returned. If the attempt is not successful and neither the error nor errortext parameters are provided then an error is raised. If the attempt is not successful and at least one of the error or errortext parameters are provided then .nul is returned and error information is output in the error or errortext objects provided.

Prototype

ppcstype1var.openudpfile ( string address, string filename, string password, integer codepage, integer error, string errortext, integer retry, integer timeout )

Parameters

Parameter	Default value	Type name	Description
address	None	string	The internet address, machine name or IP address and port number of the PPCS server providing the file to be opened.
filename	None	string	The name of the file to open.
password	None	string	The password to be used to access the file.
codepage	850	integer	The number of the OEM codepage that will be assumed to be in use by the PPCS server providing the file.
error	`.nul`	integer	Specifies an object that is used to output any error code generated during the execution of the method. This parameter must be an object, not an integer value. If `error` is not specified or is `.nul` and `errortext` is not specified or is `.nul` then any error that occurs during object creation will halt the program. If an error object or errortext object is specified and an error occurs during execution then the error code or text is output into that object and the method returns `.nul`.
errortext	`.nul`	string	Specifies an object that is used to output any error text generated during the execution of the method. This parameter must be an object, not a string value. If `error` is not specified or is `.nul` and `errortext` is not specified or is `.nul` then any error that occurs during object creation will halt the program. If an error object or errortext object is specified and an error occurs during execution then the error code or text is output into that object and the method returns `.nul`.
retry	1000000	integer	The number of microseconds between retries, if the operation is not successful immediately.
timeout	5000000	integer	The number of microseconds allowed for the operation to complete before it is assumed that it will fail.


type		ppcstype1field

simpol