System subroutines

There are various generic subroutines that have been written to simplify the development of applications. These subroutines are described here.

sysadminister

sysadminister locks all users other than the specified user (default: administrator) out of the system. This function restarts the system queues so user sessions will be terminated upon completion of their current interaction.

Example

The format of the command is as follows:

sysadminister [username] [-UNLOCK]

where:
[username] is an optional user to have access to the system. The default username is administrator.

[-UNLOCK] re-enables a locked system,

 

sysbusy

sysbusy allows for a queue to be placed into the busy state. Once a queue has been placed into the busy state, it will wait for the maximum timeout period to elapse (defined in the registry) before returning with an error. This function can be used in programs that are expected to take a long time to complete.

NB: This option is sometimes the incorrect approach. The browser windows have their own timeout settings and most often the browser window will return an error.

It is a better idea to launch the process as a phantom process and run a continuous check on this process, rather than use the sysbusy clause.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- call the busy function
CALL sysbusy
*--- user defined code follows
*
* set HTML where appropriate
*
*--- always return when code completes
RETURN


 

syscommon

The common block

Provides access to information at various levels within an application.

User programs

Developers must include the common block within their routines and must ensure that all routines that include the common block are re-compiled for new versions of the system.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- user defined code follows
*
* set HTML where appropriate
*
*--- always return when code completes
RETURN

 

syscreate

syscreate creates a new page. The page contains the same securities as the previous page and all data stored in the common block is available to the new page.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- user defined code follows
*
* set HTML where appropriate
*
*--- call a page called 'syslogon'
CALL syscreate("syslogon",html)
*--- always return when code completes
RETURN

 

 

sysdebug

sysdebug is the debugger routine. This routine is called from the TCL command prompt in the account that you wish to debug. The routine takes two parameters. The first parameter is an alphanumeric string that specifies the name of the debug session. The second parameter specifies the verbosity level of the debugger.

Debug Verbosity Levels
v1 - displays no information
v2 - displays the sysexename and the UA Request Variables
v3 - dispays v2 and all the CGI / environment variables

Example

To start a debug session named "bob1" with a verbosity level 2:
> sysdebug bob1 -v2

 

 

sysdecrypt

sysdecrypt is used to decrypt any data previously encrypted and contained in the syscryptdata common block item. The decrypted data is passed back in the same common block variable.

For successful decryption to take place, the key must be decrypted with the same set of keys as they were encrypted.

NB: It is vitally important that encryption keys be backed up and stored offsite along with other backups of the system.

Example

...
*--- let us decrypt some text
READ texttodecrypt FROM filvar,id ELSE
CRT "Error reading record"
RETURN
END
*--- assign to common block variable
syscryptdata = texttodecrypt
*--- call the decryption function
CALL sysdecrypt
*--- check for an error
IF syscrypterr THEN
CRT "An Error occurred !"
RETURN
END
*--- reassign the result
decryptedtext = syscryptdata
*--- output the result
CRT "Decrypted data: ":decryptedtext

OUTPUT
======
Decrypted data: Hello World

 

 

sysdisable

sysdisable is a routine that allows the administrator to disable the entire account to all web users. This option will not allow for queues to be started and users will receive the disabled error message in their browser windows.

Example

> sysdisable

 

 

sysencrypt

sysencrypt is used to encrypt any data set in the syscryptdata common block item. The encrypted data is passed back in the same common block variable.

Before encryption can take place, a set of encryption keys must have been created or imported.

NB: It is vitally important that encryption keys be backed up and stored offsite along with other backups of the system.

Example

...
*--- let us encrypt some text
texttoencrypt = "Hello World"
*--- assign to common block variable
syscryptdata = texttoencrypt
*--- call the encryption function
CALL sysencrypt
*--- check for an error
IF syscrypterr THEN
CRT "An Error occurred !"
RETURN
END
*--- reassign the result
encryptedtext = syscryptdata
*--- output the result
CRT "Encrypted data: ":encryptedtext

OUTPUT
======

Encrypted data: 4F12AB100F948BCB7C2ECC0192

 

sysenable

sysenable is a routine that allows the administrator to re-enable an account that has been disabled with the sysdisable command.

Example

> sysenable

 

 

sysfiledel

sysfiledel is used by a developer to delete a record from a database file. The database file that the record is deleted from is indicated by the sysfile common block item. The record that is deleted from the file is indicated by the sysid common block item. If the developer would not like any confirmation to occur, then syssubparm must be set to "skip". If the developer has a confirmation checkbox (indicated by setting sysreserved<3> to on/off) on the page, then the record will not be deleted from the file unless sysreserved<3> is set to on.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set the filename
sysfile = "MasterFile"
*--- set the record id
sysid = "12345"
*--- set the skip parameter
syssubparm = "skip"
*--- delete the record 12345 from file MasterFile
CALL sysfiledel(html)
*--- always return when code completes
RETURN

 

 

sysfileopen

sysfileopen is used by a developer to read data from a record in a database file. The record read is indicated by sysid and the file read is indicated by sysfile. The data read from the file is stored in sysdata. All values in syshidden and sysreserved are cleared.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set the filename
sysfile = "MasterFile"
*--- set the record id
sysid = "12345"
*--- get data from MasterFile with recid 12345 to sysdata
CALL sysfileopen(html)
*--- always return when code completes
RETURN

The above is equivalent to:

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- open the file
CALL sysopen("MasterFile",filevar,html)
IF html THEN RETURN
*--- read the data into sysdata
READ sysdata FROM filevar, "12345" ELSE sysdata=""
*--- refresh the html
CALL sysnavrefresh(html)
*--- always return when code completes
RETURN

 

 

sysfilesave

sysfilesave is used by a developer to write data to a record in a database file. The record id is indicated by sysid and the file is indicated by sysfile. The data written to the file is stored in sysdata.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set the filename
sysfile = "MasterFile"
*--- set the record id
sysid = "12345"
*--- the data to write
sysdata = "I want to write this to the file"
*--- write data to MasterFile with record id 12345
CALL sysfilesave(html)
*--- always return when code completes
RETURN

The above is equivalent to:

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- open the file
CALL sysopen("MasterFile",filevar,html)
IF html THEN RETURN
*--- the data to write
sysdata = "I want to write this to the file"
*--- write the data to the file
WRITE sysdata ON filevar, "12345"
*--- refresh the html
CALL sysnavrefresh(html)
*--- always return when code completes
RETURN

 

 

sysftn

sysftn evaluates DIRT tags in a string. The subroutine parses the input string and converts any valid DIRT tag into its value. For a list of the available DIRT tags, refer to the DIRT Elements section.

Note: It is not recommended to use this function within your subroutines as the values of items can rather be programmatically retrieved.

Also, rather use the function on short sections of a string than long strings. ie: Call the function multiple times on short sections of the string, rather than calling the function once.

NB: This function can significantly affect the performance of your system if used on strings that are too long.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- the string
string1 = "sysdata<2> is {{variable||sysdata||2}}"
*--- convert the dirttag in string 1 to its value
CALL sysftn(string1)
*--- always return when code completes
RETURN

 

 

syslogon

syslogon is a routine that checks the credentials of a logon request. The routine requires the username and password of the user to be passed through in the URL in variables called AuthLogonUser and AuthLogonPwd respectively. These variables are usually defined by using named text boxes. The routine checks whether the password is correct against the encoded password on the system and whether or not the password has expired. Next, it assigns the users security groups and then calls syscreate to create the startup page specified for that user, or the default startup page defined for the system if none is specified for that user.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- log the user onto the system
CALL syslogon(html)
*--- always return when code completes
RETURN

 

 

sysmail

sysmail is used to send email via the AutoMail Service. The following array must be defined to call the sysmail routine.

sysemail<sysmailfrom> Sender's name and email address
sysemail<sysmailto,x> Destination names and email addresses
sysemail<sysmailcc,x> Carbon copy email addresses
sysemail<sysmailbcc,x> Blind carbon copy email addresses
sysemail<sysmailsubj> Message subject
sysemail<sysmailatt,x> Attachments
sysemail<sysmailmsg> Message body
sysemail<sysmailhtml> is a 0/1 (false/true) indicator as to whether the message body is in text or html format

 

The formats of the sender/destination names and addresses are as follows:

    Real Name,[email protected] e.g. Joe Bloggs,[email protected]

The format of the attachment array is as follows:

    Generated File Name,Real File Name e.g. 73094297.000,MyFile.doc

Each account contains sysmailin, sysmailout, and sysmailatt VOC file pointers. These point to a set of directories required for sending and receiving mail.

N.B. If an attachment is specified it must be copied into the sysmailatt directory with the same filename as the Generated File Name stored in the attachment array before calling sysemail. A Generated File Name is used as each mail must contain its own copy of the attachment in the sysmailatt directory. The attachment that corresponds to the message is deleted from sysmailatt automatically once the mail has been sent.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- clear out sysemail
sysemail = ""
*--- set the mail from address
sysemail<sysmailfrom> = "Bob Bloggs,[email protected]"
*--- set the mail to address'
sysemail<sysmailto,1> = "Ian Fish,[email protected]"
sysemail<sysmailto,2> = "Zac Smith,[email protected]"
*--- set the mail cc address
sysemail<sysmailcc,1> = "Fred Nat,[email protected]"
*--- set the mail subject
sysemail<sysmailsubj> = "Test message subject"
*--- set the mail message
sysemail<sysmailmsg> = "<h1>Test message</h1>"
*--- set the html indicator to on
sysemail<sysmailhtml> = 1
*--- call the email program
CALL sysmail
*--- always return when code completes
RETURN

 

 

sysnavback

sysnavback returns the last different page in the syssessions file for the current session. All data values in the common block are replaced with what they were when the returned page was submitted.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- return to the previous page
CALL sysnavback(html)
*--- always return when code completes
RETURN

 

 

sysnavbackto

sysnavbackto returns to a specific page. The routine returns to the last instance in the syssessions file of the page defined by syssubparm. All data values in the common block are replaced with what they were when the returned page was submitted.

Warning

The page that you wish to return to must have existed in the current session, otherwise the current page will be recreated.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set the return page
syssubparm = "syslogon"
*--- return to page "syslogon"
CALL sysnavbackto(html)
*--- always return when code completes
RETURN

 

 

sysnavrefresh

sysnavrefresh repaints the current page. It re-calls the routines associated with the page and loads the data values defined in the common block. Pre-page, on-page and post-page routines are also re-called.

Warning

Never use sysnavrefresh in a prepage, postpage or onpage routine as this will cause an infinite loop. It should only be called on a trigger routine or directly from the object as its "Trigger Option".

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- refresh the current page
CALL sysnavrefresh(html)
*--- always return when code completes
RETURN

 

 

sysopen

sysopen is a generic routine created to open a file to a file handle. The file is specified as the first parameter, the file handle is specified as the second parameter and the error variable is the third parameter. If an error occurs, an html page will be returned in the error parameter. You may choose to return this page, or a custom error, depending on where the failure occurs.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- open the sysusers file
CALL sysopen("sysusers",filevar,html)
IF html THEN RETURN
*--- perform code specific to this routine
...
*--- refresh the page
CALL sysnavrefresh(html)
*--- always return when code completes
RETURN

OR
SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- open the sysusers file
CALL sysopen("sysusers",filevar,err)
IF err THEN
syserrmsg = "Could not open the sysusers file"
RETURN
END
*--- perform code specific to this routine
...
*--- refresh the page
CALL sysnavrefresh(html)
*--- always return when code completes
RETURN

 

 

syspageparms

syspageparms enables the easy extraction of form variables from a web builder page. Form variables may be extracted one at a time into separate variables, or all at once into one value mark delimited variable

Examples

One at a time

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- pull out form variables
CALL syspageparms("txtName",nme)
CALL syspageparms("txtAddress",addr)

RETURN

All at once

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- pull out form variables
CALL syspageparms("txtName,txtAddress",parms)
*--- Separate them out
nme = parms<1>
addr = parms<2>

RETURN


syspostscript

syspostscript inserts a java-script string after the </body> tag on a page. The java-script string is passed to the routine as a parameter. The <script> and </script> tags are automatically inserted.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- setup the html page
CALL sysnavrefresh(html)
*--- setup the javascript string
*--- firstly add the function to call
string1 = "function AlertPage() {":crlf
string1 := " alert('":syspage:"');":crlf
string1 := "}":crlf
*--- now call the function
string1 := "AlertPage();":crlf
*--- add the above script to the page
CALL syspostscript(string1)
*--- always return when code completes
RETURN

 

 

syspurge

syspurge purges sessions older than a specified time from the syssessions file. The routine is normally run from the TCL command prompt and is run in the account whose session file you wish to purge. It is very important to run this routine, as it will improve the response times of interactions. The routine takes one parameter, the number of days of sessions that must remain in the syssessions file.

Example

If you would like to purge all sessions that were not generated in the last two days:
> syspurge 2

 

 

syspurgewk

syspurgewk purges the syswork file. The routine is normally run from the TCL command prompt and is run in the account whose syswork file you wish to purge. This routine only needs to be run on development accounts. The routine takes one parameter, the number of days of objects that must remain in the syswork file.

Example

If you would like to purge all objects that were not generated in the last two days:
> syspurgewk 2

 

 

syspwdenc

syspwdenc encrypts a string. This encryption mechanism makes use of one-way encryption. This means that once a string has been encrypted, there is no way of decrypting it. Since the users' passwords are stored encrypted in the sysusers file, the only way for a developer to check the credentials of a user logging in is to encrypt the supplied password and check whether the encrypted supplied password and the password in the sysusers file are the same. The routine takes two parameters. The first parameter is a string to encrypt; the second parameter is the returned encrypted string.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- open the sysusers file
CALL sysopen("sysusers",sysusers,err)
IF err THEN RETURN
*--- check the supplied password against the
* password in the sysusers file
*--- get the users name
username = "bob5"
*--- get the users password
userpasswd = "bob_password"

*--- call the encryption routine
encryptpasswd = ""
CALL syspwdenc(userpasswd,encryptpasswd)

*--- validate the password in the sysusers file
* against the returned encrypted password
*--- read the record from the sysusers file
READ recuser FROM sysusers,username ELSE recuser=""
*--- check if the passwords are the same
IF recuser<2> # encryptpasswd THEN
*------ passwords are not the same - return error
syserrmsg = "Invalid password supplied"
CALL sysnavrefresh(html)
RETURN
END

*--- if the password is ok then call post logon page
CALL syscreate("sysenv",html)
*--- always return when code completes
RETURN

 

 

sysread

sysread is used to read a record from a file that has been marked by the system as being encrypted. The function can be used as a replacement for the BASIC READ statement, and follows it's conventions in parameter ordering. It is a good idea to always use this function as it will simplify changes to the system if you decide to encrypt a file at a later stage.

There are 3 parameters; record, fileid, recordid.

record This parameter will contain the un-encrypted record after a successful read.
fileid The id of a file previously opened with one of the BASIC OPEN methods.
recordid The id of the record you wish to read from the file.

The function returns true on success, and false on an error.

Example

SUB TrgGetRecord(html)
*--- sysread trigger routine example
INCLUDE sysbp syscommon
*--- open a file
CALL sysopen("filename",fileid,html)
*--- check for an error
IF html THEN return
*--- set the record to retrieve
id = "UniqueId"
*--- read the record into sysdata
IF sysread(sysdata,fileid,id) ELSE
syserrmsg = "Error reading record !"
END
*--- refresh the page
CALL sysnavrefresh(html)
*--- all done
RETURN

 

 

sysreadu

sysreadu is used to read a record from a file that has been marked by the system as being encrypted. The function can be used as a replacement for the BASIC READU statement, and follows it's conventions in parameter ordering. It is a good idea to always use this function as it will simplify changes to the system if you decide to encrypt a file at a later stage.

To indicate a locked record, the function sets the common block variable, syslocked, to 1 (true). This variable will only be set on failure to read.

There are 3 parameters; record, fileid, recordid.

record This parameter will contain the un-encrypted record after a successful read.
fileid The id of a file previously opened with one of the BASIC OPEN methods.
recordid The id of the record you wish to read from the file.

The function returns true on success, and false on an error.

Example

SUB TrgGetRecord(html)
*--- sysreadu trigger routine example
INCLUDE sysbp syscommon
*--- open a file
CALL sysopen("filename",fileid,html)
*--- check for an error
IF html THEN return
*--- set the record to retrieve
id = "UniqueId"
*--- read the record into sysdata
IF sysreadu(sysdata,fileid,id) ELSE
IF syslocked THEN
syserrmsg = "The record is locked !"
END ELSE
syserrmsg = "Error reading record !"
END
END
*--- refresh the page
CALL sysnavrefresh(html)
*--- all done
RETURN

 

 

sysrestart

sysrestart is the command that shuts down the queues for your account. These queues are automatically re-launched when the users connect. The queues must be restarted every time a change is made to a program as the programs object file is cached inside the queue. The queues must also be restarted when changes are made to the syscontrol, parms record, as these parameters are cached by the queue when the queue is launched.

Example

To restart all the queues in the current account:
> sysrestart

 

 

sysreg

sysreg is a routine that extracts information from the registry. The routine can be used on both UNIX and NT systems, but supports only the ability to read from the registry.

The routine takes two parameters, the first specifying the path in the registry to read and the second specifying the return variable.

The routine either returns "Error" or the registry entry.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
parms = ""
retrvar = ""
*--- set the path to read if NT
parms<1> = "HKEY_LOCAL_MACHINE\Software\pSygn\General"
*--- set the path to read if UNIX
* parms<1> = "/etc/pSygn/pSygn.conf"
*--- set the item to read
parms<2> = "Default Account"
*--- get the value from the registry
CALL sysreg(parms,retrvar)
*--- check the return value
IF retrvar = "Error" THEN
syserrmsg = "Custom Error Msg"
RETURN
END
*--- otherwise do function calls
.
.
.
*--- always add return at end function
RETURN

 

 

sysregdel

The sysregdel function is used to delete configuration data from the registry (under the Windows operating system), or from a set of configuration files (under the UNIX operating system).

This function does not have any parameters, but uses a series of common block items as defined earlier in this manual. It uses the sysregpath, sysregvar, and sysregerr equates.

The sysregpath equate should contain the registry path or configuration file to delete from, or be deleted. The sysregvar equate can either be blank (which deletes the entire registry key or configuration file), or it can contain the description of an item you would like to delete.

Below are two examples, one for Windows and the other for UNIX, respectively:

Windows Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set up the registry path
sysreg<sysregpath> = "HKEY_LOCAL_MACHINE\Software"
sysreg<sysregpath>:= "\MyAppSettings"
*--- set up the variable
sysreg<sysregvar> = "My Configuration Parameter"
*--- call the registry delete function
CALL sysregdel
*--- check the return parameter
IF sysreg<sysregerr> # 0 THEN
*------ report error
syserrmsg = "Failed to delete registry item !"
END
*--- redraw the page
CALL sysnavrefresh(html)
*--- done
RETURN

The above example will delete the registry variable "My Configuration Parameter" and it's associated value from the "HKEY_LOCAL_MACHINE\Software\MyAppSettings".

If the line containing the following text
sysreg<sysregpath>:= "\MyAppSettings"
were to read
sysreg<sysregpath>:= ""
Then the entire key "MyAppSettings" and all it's values would be deleted.

UNIX Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set up the registry path
sysreg<sysregpath> = "/etc/MyApp/MyApp.conf"
*--- set up the variable
sysreg<sysregvar> = "My Configuration Parameter"
*--- call the registry delete function
CALL sysregdel
*--- check the return parameter
IF sysreg<sysregerr> # 0 THEN
*------ report error
syserrmsg = "Failed to delete registry item !"
END
*--- redraw the page
CALL sysnavrefresh(html)
*--- done
RETURN

As before, this example will delete the variable "My Configuration Parameter" from the file called "MyApp.conf" in the "/etc/MyApp" directory.

 

 

sysregread

The sysregread function is used to read configuration data from the registry (under the Windows operating system), or from a set of configuration files (under the UNIX operating system).

This function does not have any parameters, but uses a series of common block items as defined earlier in this manual. IT uses the sysregpath, sysregvar, and sysregval equates.

The sysregpath equate should contain the registry path or configuration file to read. The sysregvar equate can either be blank (which returns a structure of all items below this point into the sysregval equate), or it can contain the description for an item whose value you want to retrieve into the sysregval equate.

Below are some examples, two for Windows and the other for UNIX, respectively:

Windows Example 1

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set up the registry path
sysreg<sysregpath> = "HKEY_LOCAL_MACHINE\Software"
sysreg<sysregpath>:= "\MyAppSettings"
*--- set up the variable
sysreg<sysregvar> = "My Configuration Parameter"
*--- call the registry read function
CALL sysregread
*--- check the return parameter
IF sysreg<sysregerr> # 0 THEN
*------ report error
syserrmsg = "Failed to read registry item !"
END
*--- place the value returned into arbitrary data value
sysdata<1> = sysreg<sysregval>
*--- redraw the page
CALL sysnavrefresh(html)
*--- done
RETURN

Windows Example 2

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set up the registry path
sysreg<sysregpath> = "HKEY_LOCAL_MACHINE\Software"
sysreg<sysregpath>:= "\MyAppSettings"
*--- set up the variable and value
sysreg<sysregvar> = ""
*--- call the registry read function
CALL sysregread
*--- check the return parameter
IF sysreg<sysregerr> # 0 THEN
syserrmsg = "Failed to read registry item !"
END
*--- place the value returned into arbitrary data value
sysdata<1> = sysreg<sysregval>
*--- redraw the page
CALL sysnavrefresh(html)
*--- done
RETURN

RAISE the sysregval item to get the following structure:

0001 KeyName [] KeyName\SubKeyName [] KeyName\SubKeyName\SubSubKeyName
0002 [] VariableName1 | VariableName2 | VariableName3 [] VariableName4
0003 [] ValueName1 | ValueName2 | ValueName3 [] ValueName4
0004 [] ValueTypeDS | ValueTypeDS | ValueTypeDS [] ValueTypeDS

Where:
    00X = Fields. char 254 delimited (@am)
    [] = char 253 (@vm)
    | = char 252 (@svm)
    KeyName = The virtual path from the root queried
    VariableName = Multi-valued vars in registry for that KeyName
    ValueName = Associated Values
    ValueTypeDS = Associated type: "D" for Numeric, "S" for string

UNIX Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set up the registry path
sysreg<sysregpath> = "/etc/MyApp/MyApp.conf"
*--- set up the variable
sysreg<sysregvar> = "My Configuration Parameter"
*--- call the registry read function
CALL sysregread
*--- check the return parameter
IF sysreg<sysregerr> # 0 THEN
syserrmsg = "Failed to read registry item !"
END
*--- place the value returned into arbitrary data value
sysdata<1> = sysreg<sysregval>
*--- redraw the page
CALL sysnavrefresh(html)
*--- done
RETURN

 

 

sysregwrite

The sysregwrite function is used to write configuration data to the registry (under the Windows operating system), or to a set of configuration files (under the UNIX operating system).

This function does not have any parameters, but uses a series of common block items as defined earlier in this manual. It uses the sysregpath, sysregtype, sysregvar, sysregval, and sysregerr equates. The sysregtype item is only valid on Windows platforms and can be K, S, or D. S and D stand for String and DWord, which imply textual or numeric data respectively. K stands for Key and is used in a case where only the registry path stored in sysregpath is to be created

Below are two examples, one for Windows and the other for UNIX, respectively:

Windows Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set up the registry path
sysreg<sysregpath> = "HKEY_LOCAL_MACHINE\Software"
sysreg<sysregpath>:= "\MyAppSettings"
*--- set up the registry type (K,S,D)
sysreg<sysregtype> = "S"
*--- set up the variable and value
sysreg<sysregvar> = "My Configuration Parameter"
sysreg<sysregval> = "Value of my parameter"
*--- call the registry write function
CALL sysregwrite
*--- check the return parameter
IF sysreg<sysregerr> # 0 THEN
*------ report error
syserrmsg = "Failed to write registry item !"
END
*--- redraw the page
CALL sysnavrefresh(html)
*--- done
RETURN

UNIX Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- set up the registry path
sysreg<sysregpath> = "/etc/MyApp/MyApp.conf"
*--- set up the variable and value
sysreg<sysregvar> = "My Configuration Parameter"
sysreg<sysregval> = "Value of my parameter"
*--- call the registry write function
CALL sysregwrite
*--- check the return parameter
IF sysreg<sysregerr> # 0 THEN
*------ report error
syserrmsg = "Failed to write registry item !"
END
*--- redraw the page
CALL sysnavrefresh(html)
*--- done
RETURN

This above example will create a file called "MyApp.conf" in the "/etc/MyApp" directory on the filesystem in the following format:

My Configuration Parameter=Value of my parameter

 

 

syssecchk

syssecchk validates the current user against a list of security groups. The list of security groups (an attribute marked array) is passed to the routine as the first parameter. The second parameter is the return value from the syssecchk routine. The routine returns 1 if the security check was passed and 0 if it was not. The security check is passed if any of the groups in the list passed to the routine match any of the groups defined in the sysusers file.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- setup the list of security groups
securegroup = ""
securegroup<1> = "branches"
securegroup<2> = "regions"
securegroup<3> = "hdoffice"
*--- check if the current user belongs to any of the
* above security groups
CALL syssecchk(securegroup,secpass)
*--- check if user was validated
IF secpass = 0 THEN
*------ the security check failed
*
*
ELSE
*------ the security check passed
*
*
END
*--- always return when code completes
RETURN

 

 

sysshell

sysshell function checks whether to call an NT or UNIX version of the shell command. This function assists developers in writing portable code as long as the functions they call available on both architectures.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- call the shell utility
CALL sysshell("mkdir MyDirecory",xyz)
*--- check the return parameter
IF xyz # "" THEN
syserrmsg = "Custom Error Msg"
RETURN
END
*--- otherwise do function calls
.
.
.
*--- always add return at end function
RETURN

 

 

systable

systable inserts a table into the page. The table you would like to insert is specified as the first parameter and the string into which you would like to insert it (normally html) is the second parameter.

Example

SUB subname(html)
*--- include the common block
INCLUDE sysbp syscommon
*--- load the table
CALL systable("syslogon",html)
*--- always return when code completes
RETURN


 

 

syswrite

syswrite is used to write a record to a file that has been marked by the system as being encrypted. The function can be used as a replacement for the BASIC WRITE statement, and follows it's conventions in parameter ordering. It is a good idea to always use this function as it will simplify changes to the system if you decide to encrypt a file at a later stage.

To indicate a locked record, the function sets the common block variable, syslocked, to 1 (true). This variable will only be set on failure to write.

There are 3 parameters; record, fileid, recordid.

record This parameter must contain the un-encrypted record to be written.
fileid The id of a file previously opened with one of the BASIC OPEN methods.
recordid The id of the record you wish to write onto.

The function returns true on success, and false on an error.

Example

SUB TrgSaveRecord(html)
*--- syswrite trigger routine example
INCLUDE sysbp syscommon
*--- open a file
CALL sysopen("filename",fileid,html)
*--- check for an error
IF html THEN return
*--- set the record to save
id = "UniqueId"
*--- write the record in sysdata onto the file
IF syswrite(sysdata,fileid,id) THEN
syserrmsg = "Record successfully written."
END ELSE
IF syslocked THEN
syserrmsg = "The record is locked and"
syserrmsg:= "cannot be written !"
END ELSE
syserrmsg = "Error reading record !"
END
END
*--- refresh the page
CALL sysnavrefresh(html)
*--- all done
RETURN