Oliver-Liberty Gateway Reference Manual

Gateway Reference Guide
Version 5.2A
This guide explains the use of the Gateway parameters and commands. Gateway provides a generic method of searching and publishing data from any Concordance database into a Web environment. We have assumed the reader has a good knowledge of HTML.
Table of Contents
Overview...................................................................................................................................................2 Gateway Forms.........................................................................................................................................3 Concordance.............................................................................................................................................5 Installation................................................................................................................................................6 Installation Security settings..................................................................................................................8 Gateway Parameters...............................................................................................................................13 Gateway Registry Configuration................................................................................................................21 HKEY_LOCAL_MACHINE\Software\Softlink International\Gateway.......................................................21 HKEY_LOCAL_MACHINE\Software\Softlink International\Gateway\{app}............................................21 The Gateway INI File.............................................................................................................................23 Browse Parameters.................................................................................................................................27 Gateway Commands...............................................................................................................................28 SESSION Database................................................................................................................................90 Common Errors......................................................................................................................................92
Page 1 of 93
Overview
The Gateway is a CGI program designed to interact between a web server and Concordance databases. Gateway forms control the operation of the program through Gateway commands encountered while processing the forms. A Gateway form is a standard text/html file with embedded Gateway commands. A Gateway command is any HTML statement that begins: <GATEWAY or  or similar, this is the current directory in which the Gateway program is being executed, directories that are not absolutely specified in the Gateway INI file should be made relative to this directory.
8.
9.
10. Modify the forms as necessary using the instructions in this guide and the samples provided. Page 7 of 93
Installation Security settings

Security is typically our most common problem when dealing with installation problems. There are two scenarios to consider, one is when the databases are on the same machine as the web server, and the other is when the databases are on another web server. If you are using a mixed environment (for example NetWare and NT) then you will probably need to consider that your users will not be authenticated against the web server, therefore plan on utilising the second of our following scenarios. With regard to anonymous access, since IIS 4 we recommend a separate anonymous user is established and used by the Gateway. We recommend IUSR_GATEWAY as the login name and making this a domain account (not a machine local account). Please note the password assigned, as this will be required when specifying the login name to the Internet Server Manager. 1. Same server Anonymous access Normally this scenario implies that you do not have authentication on the web server that is the end users logins are not known to the web server, and therefore we allow anonymous access only. Security settings for anonymous user Gateway directory Data directory (contains SESSION.DCB) Forms directory Temp directory (contains temporary files) TEMP (environment variable location, i.e. C:\TEMP) Read and Execute Change Read only Change Change
Authenticated access The Anonymous User is not typically used in this case. By default Microsoft NT will authenticate the user and execute the program based upon the users security. In this case the users must have the following access
Security settings for all user access Gateway directory Data directory (contains SESSION.DCB) Forms directory Temp directory (contains temporary files) TEMP (environment variable location, i.e. C:\TEMP) Read and Execute Change Read only Change Change
Page 8 of 93
Gateway Reference Guide 2. Data on different server When the data is on a different server the security becomes more complicated. As mentioned above Microsoft NT will authenticate the user on the Web server machine for local security. When the Gateway program tries to open the databases on the data server it is challenged for authentication. The program passes the users name, but the Web server machine unfortunately does not hold the password therefore authentication on the Data server fails and the databases are not opened. (Depending on your server policy, a number of invalid security attempts may cause a login name to be locked out). To resolve this issue we recommend that an anonymous user is setup to provide this access. As a standard we recommend IUSR_GATEWAY, the configuration of the user should be similar to your standard anonymous user, except that IUSR_GATEWAY should be a domain account (if using domains). To make the Web server use the anonymous security we must change the permissions on the Gateway program, make it executable by the anonymous user only. The following table indicates how the security should be configured. Security settings for IUSR_GATEWAY Gateway directory Data directory (contains SESSION.DCB) Forms directory Temp directory (contains temporary files) TEMP (environment variable location, i.e. C:\TEMP) Concordance databases Read and Execute Change Read only Change Change Read or Change as necessary for desired actions
While this now enables access for the anonymous user, Windows NT security precedence expects user authentication to be performed first, and if this is not available then the anonymous user security is employed. Therefore we have to take away Execute access from all other users. Security on settings for other users Gateway directory Any permissions except File Execute
When NT tries to authenticate the user to execute the Gateway program it will fail, however it will automatically attempt to use the anonymous user access, and therefore succeed. Further security access to other servers is then gained using the anonymous user permissions. Within the Web Server configuration tool you should also be able to specify the type of access and security applied to the directories. (On an IIS server this is performed within the Microsoft Management Console). Security on settings for the Web server Gateway directory Allow anonymous access
Page 9 of 93
and specify the domain\IUSR_GATEWAY user, type and confirm the password. Ensure the Windows NT Authentication and Basic Clear Text options are not checked. This will again ensure that only anonymous access is granted for executing the Gateway.
In a trusted domain environment (i.e. with NT domains in use) it is important that the Intranet User logs onto the domain and not just the local machine. IIS will by default install a local login only, therefore you should modify this in your IIS admin screens to specify the username as: domainName/IUSR_machinename. Identifying the user There are a number of instances when you want to be able to identify who the user is, particularly when you are allowing database updates or additions. Also with regard to security it is important to know who the user is before allowing access to secured databases, records, or fields. There are two main options here: 1) Validating the username and password If the user is basically anonymous, or using a computer provided for public access then you will want to identify the user through a login screen. A sample screen exists in the forms directory called logon. Use the Gateway to display this form, fill in the fields with a valid username and password (from the CLIENTS database) and your user will be validated for the length of this Gateway session. 2) Identifying the user by their network sign-on Where the user is actually signed onto a network (in particular an NT/2000 domain), then the Web server can be configured to perform NT Authentication (this is the default setting). Where the user is authenticated the Web server (e.g. IIS) will run the Gateway with the authenticated users security. This also allows the Gateway to access the users login name, using a statement like: <input type=hidden name=username value=<gateway parameter name=remote_user>> This works ok until the databases reside on a different server. In this instance we may be forcing the Gateway to use the anonymous sign-on as described above in the Permissions section. Now the Windows NT will not perform the authentication required to identify the user. In this instance we need to utilise a small program called GWID.EXE.
Page 10 of 93
GWID.EXE is a CGI program designed to send a form back to the requesting user, however on the way it will replace the text  with the actual authenticated sign-on. To specify the form name, pass it as a parameter to the GWID program in a similar manner to the Gateway forms, except we use the parameter name FORM, for example: http://servername/scripts/gwid/gwid.exe?form=gwid\premain To identify the users sign-on, however, GWID.EXE must be configured so that it can not be executed by the anonymous user, this is set by the administrator in the security settings for GWID.EXE. Use the Internet Server Manager to ensure anonymous access is not valid for this gwid directory, and that only NT authentication is allowed. Note: It is suggested that GWID.EXE is placed in a separate directory to the Gateway and the security set on the directory, this will ensure the security is maintained even if the program is updated. The process can then be: http://servername/scripts/gwid/gwid.exe?form=gwid\premain This will force the web server to authenticate the remote user (as the program cant be run anonymously), and replace the string <! --USER--> with the username. A sample premain might be: <html> <head> <meta http-equiv=refresh content=0; URL=http://servername/scripts/gateway.exe? displayform=main&username=> </head> <body> Logging into the Gateway </body> </html> With both the Gateway and the GWID programs in operation, your final security settings will be similar to: NT security for the GWID directory Administrators Users IUSR_GATEWAY Web server security for the GWID directory Anonymous access OFF Full access Read and Execute None
Page 11 of 93
Basic clear text Windows NT Authentication NT security for the Gateway directory (and sub-directories) Administrators Users IUSR_GATEWAY Web authors Web server security for the Gateway directory Anonymous access
OFF ON
(All) (RCDPO) not execute None Change (RXCD) (RCD) not execute
ON Domain\IUSR_GATEWAY (type and confirm password)
Basic clear text Windows NT Authentication NT security for the Gateway application databases Administrators Library staff Users IUSR_GATEWAY (can be a member of the Library group)
OFF OFF
Full access Change None Change
Page 12 of 93
Gateway Parameters
ALWAYSRESULTS=TRUE When set to TRUE, if a full text search is being done (see SRCHFT value in the description for SRCHxxfield below) and no results would be returned, further searches are done until results are found. (Even if the search is not a SRCHFT, using the AlwaysResultsParm parameter can still enable this, see below). So if you search for Octopus carpets and no results are produced, the gateway will broaden the search to Octopus* carpets*, then Octopu* carpet*, then Octop* carpe*, then Octo* carp*, etc until at least one result is found. If the SRCHFT term contains advanced search characters (. or or = or ,) or if it contains concordance search words (lt or le or eq or gt or ge or ne or co or nc or wl or ol) then a broadened search is not attempted. If a broadened search is done, the gateway command TERMRESULTS will display a message such as Search broadened to Octo* carp*. AlwaysResultsParm=value When ALWAYSRESULTS is set to TRUE but you wish it to operate on something other than the SRCHFT parameter, set this to the name of the parameter that you wish to use. For example AlwaysResultsParm=SRCHFTTITLE. When set this will generate a debug file called "gateway.log" in the gateway \ temp directory. You may use this file to assist your debugging. Otherwise it will only be used on request of technical staff. This parameter is used as a switch to indicate a Concordance search is to be processed. If you do not have this parameter no search will take place. The form is used to format the search results reporting the databases being searched, total hits, and other search information. You may use an empty file is necessary. By convention we call this file srchnull. The search form is processed after the update
DEBUG=1
SEARCHFORM="searchFormName"
Page 13 of 93
form but before the display form. DATABASE=databaseName Specify the database to be searched. You can repeat this parameter as often as necessary up to the Concordance limit for concatenating databases. Alternatively you can have Gateway concatenate the databases under one statement by specifying DATABASE=database,database DROPFTTERMS Prevents gateway from dropping the terms from a full text search, forcing searches to return 0 results unless the full-text search has matches. Changes the way Gateway processes SRCHAD parameters more than 100 characters long. The search may be slower, but combinations of several long searches are possible. SRCHxxfield=search text The SRCH parameters identify what to search, how to search it, and what to search for. You can have as many of these parameters as desired. You may implement a form search by associating various textboxes with specific fields. Replace "xx" with a code: AD - Advanced search AV - Any value CO - Field contains FT - Standard full text search FX - Full text excluding this field MA - Match exactly MM - Match multiple entries NE - Not equal NV - Null value
PROCLONGSRCHAD=TRUE
Page 14 of 93
LR - The lowest possible value HR - The highest possible value WL - Within two values Replace "field" with a valid fieldname or field group. Values for the WL (within limits) operator should consist of range separated by a comma or hyphen, for example: 1970-1975 or 1/1/1997,31/1/1997 Value for the MM (match multiple) operator can be lists of items separated by spaces or newline characters. All spaces are replaced by commas prior to the search. This format is useful is you want to enter multiple values into a text area, the text area name will be SRCHMMfieldName, and each value, although on a separate line, will be searched as though they were comma separated. Examples: SRCHFTTITLE - full text search on Title SRCHLRDATE - the date must be >= the value SRCHFT full text search across all fields In some instances it is necessary to insert a date into the search strategy, the Gateway program will automatically insert a date value where it finds the text TODAY(n,x) where n is the number of days to add or subtract from todays date, and x is a valid format string. Valid format strings include DMY (DD/MM/YYYY), MDY (MM/DD/YYYY), and YMD (YYYYMMDD). The default is DMY. For example: TODAY(0) is replaced by todays date in a DD/MM/YYYY format. TODAY(30,MDY) will be replaced by the date 30 days previous in an MM/DD/YYYY format. If you want a date specific search result, but you only want the most current date value, you can specify CURRENT(s) where s is the
Page 15 of 93
date style, DMY, MDY, or YMD. The CURRENT(s) search will locate the records closest to todays date counting backwards, that is, the program will try for results with todays date, if there are none then it will try yesterdays date, if none it will continue to work backwards until it finds some resulting records or reaches 31 days previously (it will stop searching after 31 days) and return an empty result set. SLMTxxfield=search text The SLMT code operates in a similar fashion to the previous SRCH. The difference is in the way the Gateway treats the search result. The SLMT search result acts as a record limiter against the target database. Therefore an SLMT search can identify a section of the database, however a SRCH search within this document subset can still resolve to a null result. An example of the SLMT in use would be a branch library wanting to restrict their searching to their collective records only. The SLMT can be used to search for the collection code. Search processed by SRCH codes can still result in zero results, else the results will be the normal results expected. SORT=fieldname Requests that the current search result is sorted by the selected field. You can select any fieldname from the current database, and optionally append _Asc or _Desc to the name to affect the sequence. (_Asc is the default). You may specify multiple SORT fields by repeating the selection or input field. The order of these fields within the parameter list (or the form) will determine the order in which the records are then sorted, that is, DATE within TITLE or TITLE within DATE etc. CUSTOMSORT=fieldname Use of the CUSTOMSORT parameter is exactly the same as the SORT parameter, except some fields will be sorted using builtin modifiers. These fields are: TITLE ignores leading A, An and The FILENO pads leading zeros to parts
Page 16 of 93
LOCATION pads leading zeros LEADTERM uppercases content See also the <GATEWAY SORT> command. OPERATOR=operator The default operator for Concordance is normally ADJ0 (adjacent within 0 words), and while this works in some instances it does not take into account stop-words. You can use the OPERATOR parameter to override the default. Valid operators are any valid Concordance operator, these are: AND OR XOR NOT SAME ADJx NEARx Where x is a number from 0 to 99. The user can of course override the default simply by typing the operator between the terms. DISPLAYFORM ="displayFormName" or FORM_displayFormName=null Specifies the next Gateway form to be displayed. Generally there will be only one DisplayForm specified; however in the event of two the latter will override the former. You can also override the DisplayForm parameter by using a FORM_displayFormName option. This is useful where you want to use an HTML button to display one value, while specifying a form with a different name. The display form is processed as the last form; update and search forms are processed first. UPDATEFORM="updateFormName" This form is used to process new records and
Page 17 of 93
record updates. The update form is processed first, followed by the search form and then the display form. The update form in itself is not special, however if you want to append or update a record this is the best form in which to perform this function. See also the <GATEWAY UPDATE> command. USERNAME="username" Identifies the user to the program. This username can be matched against the CLIENTS database to effect a sign-on. See also the PASSWORD parameter. See <GATEWAY IF USER> for more information on sign-on. PASSWORD="password" Identifies the users password for secure operations. The username / password can be matched against the CLIENTS database for authentication. See <GATEWAY IF USER> for more information on sign-on. ALGORITHM="algorithm_type" Modifies the search algorithm used on Full Text search strategies. There are currently two modes: DEFAULT: Automatically drops terms from the strategy that do not exist in the database dictionary (i.e. ignores stop words in the search strategy). This is the default mode. ADVANCED: Processes the strategy without modification. SNAPSHOT=NO Allows the gateway to perform a database search but does not affect the current snapshot. Generally whenever a search is performed the Gateway will automatically save the search result to a snapshot file in the Gateway temporary folder. With this parameter set to NO the snapshot file will not be saved and therefore your following screens will once again process the previous search result.
Page 18 of 93
This parameter was used to display information from a related database without affecting the current list of result. SAVEFORM=null The Gateway provides an option for saving and recalling the values selected on any form, however this option is normally utilised with search forms. When the search form is redisplayed the Gateway can populate the fields with previously used values. The values of the text boxes, checkboxes, radio buttons, and selection lists can be saved and restored as necessary. The default operation is not to store the search form values. You must specify this parameter for Gateway to save the values. Values are saved to the CURR_SEARCH field in the Access database. See the associated <GATEWAY RETRIEVE > command. FROMFILE=TRUE Forces this page to be read from file, bypassing the formslibrary. A side effect of this is that translations will not occur for multilingual systems.
Page 19 of 93
APPLICATION=applicationName
While the Gateway will by default process all forms from the FormFolder specified in the Registry or INI file, a user might optionally specify an Application Name parameter to modify the folder from which the forms will be retrieved. The application names are registered either in the Registry, where Databases, Settings and other parameters can be subkeyed, or in the Gateway.ini file, in the Applications section where each entry can define a separate folder where the forms are stored for that application. If an application parameter is specified the location of the forms is stored in the APPLICATION field of the Session database. Therefore it is only necessary to specify the application parameter once at the beginning of the session. See also the Applications section in the INI file. See also the Registry entries.
NOWATCHDOG=null
The Gateway has a built-in Watchdog to monitor run-away processes (a run-away process is one that fails to complete and return a full set of HTML to the user within a predefined timeframe). If a search is entered that causes Concordance to process for an inordinately long period of time the Watchdog will terminate the process prematurely. Refer to the TerminateSeconds parameter in the Gateway INI file. To temporarily disable the Watchdog use this parameter on your search form and the monitor will not be used.
Page 20 of 93
Gateway Registry Configuration

The key value used for all Gateway entries is:
HKEY_LOCAL_MACHINE\Software\Softlink International\Gateway
Within this key should be generic values for all Gateway operations: Access ChDir DateFormat Debug Developer DisableLocalNames License TimeZone {path and name of session database} {path to root of applications} {DMY | MDY | YMD} {0 | 1} // 1 means debug is on {0 | 1} // 1 means no forms library {0 | 1} // 1 means disabled {license value} {timezone code}
Each application that employs the Gateway should define a subkey as in:
HKEY_LOCAL_MACHINE\Software\Softlink International\Gateway\{app}
Each application will then implement the necessary keys as defined below: \Gateway\{app}\Settings BoldOff BoldOn Buffer DefaultOperator ExpiryMinutes FormFolder Method SortLimit Temp TerminateSeconds UpdateExpiryMinutes Registration Name ...\Gateway\{app}\Databases {databaseName} ...\Gateway\{app}\SMTP Domain Host Sender {domain name} {host name or address} {default sender name or email address} {path to database dcb file} {html code} {html code} on | off {operator} {number of minutes} {path to forms} Post | Get {maximum sortable records} {path to temporary directory} {number of seconds} {number of minutes} {Registration Code String} {Registered Name}
Page 21 of 93
Page 22 of 93
The Gateway INI File

[Settings] The settings are parameters generic to the entire operation of the Gateway. Specify the html codes placed prior to the full text search terms in the output. The default value is <B><I> Specify the html codes placed after the full text search terms in the output. The default value is </I></B> The buffer parameter determines whether the HTML output by the Gateway should be buffered or sent immediately. A value of 0 indicates that buffering is off and all output is sent to the client as soon as it is available. This can result in many small packets of data being sent along your network. A value of on indicates that default buffering should be performed on your HTML output. This option should be more efficient for your network. DEBUG=0 Similar to the Debug parameter. With the debug parameter specified the Gateway will generate a gateway.log file in the temporary directory (refer to TEMP below). This file will grow considerable large, therefore you should not have this parameter set during normal operation. The default value is 0, this disabled the generation of the debug log. Specify any other value to generate a debug log. DEVELOPER=0 When set this Gateway will not use the Forms Library for forms. This will slow performance and translations will not occur.
BoldOn=htmlCode
BoldOff=htmlCode
Buffer={ 0 | on }
Page 23 of 93
DefaultOperator=op
Enter a system wide default operator for searching. The Concordance default is ADJ0. The Gateway default is SAME. Specify any operator as required. This value is overridden by the L3DEFOP parameter in the Access database, which in turn is overridden by the presence of the OPERATOR parameter.
ExpiryMinutes=value
Specify the number of inactive minutes before a session will automatically expire. The default value is 30. The client screen will not change, however if the user attempts to explore a link on the screen they may receive a message, error: access not allowed.
FormFolder=path
Specifies the directory where the default forms are located. These can be separate from other HTML forms because of their special nature. See also the APPLICATIONS section later in this table.
Registration=string
This is a license key indicating a registered version of the software. Contact Softlink International Limited for a valid key. Registered Name. Name string appears on all emails generated by the System. The Name is tied to the Registration string. Specify the maximum value of the Library ID records (when using Concordance / Liberty/Oliver). The default value is 69999. By default the web server will use the Get request method. This works well with most CGI programs as the parameters are passed in environment variables, however it doesnt work well when we are updating documents with large amounts of text. For this latter option we should use a request method of Post where the parameters are read from an input stream. E.g. METHOD=POST
Name=string
MAXLIBID=value
Method=requestMethod
Page 24 of 93
SortLimit=value
Limit the number of documents that can be sorted within the interface. The default value is 500. You may override this limit by adding the parameter MAXSORT=x to your sort command or the parameters passed to the Gateway.
TEMP=drive:\path
Identifies a path to a directory where temporary files will be placed. This option is used in preference to the TEMP environment variable. Number of seconds the Gateway program is allowed to process before it automatically self terminates. This value should normally be between 20 and 120 seconds. The default value is 120 seconds. To turn off this facility temporarily, pass a parameter called NOWATCHDOG to the form, it can have any value, for example NOWATCHDOG=X.
TerminateSeconds=120
UpdateExpiryMinutes=10
Specify the number of inactive minutes before an update lock will expire, allowing others to edit the record. The default value is 10 minutes. This section contains parameters for using the Liberty/Oliver replication system. You may also use this to track new and updated records into a log file. The local branch name is the code that will identify transactions initiated at this server. Identifies a path to a directory where transaction log files will be placed. This section contains parameters related to the Gateways ability to send email. Specify the SMTP server name. This will be the server where you have a valid SMTP service operating. Specify the Domain name to be used by default for this server and your own identification.
[Replication]
LocalBranchName=string
TransactionLogs=drive:\path
[SMTP]
HOST=machinename
DOMAIN=domainname
Page 25 of 93
SENDER=email@address
Specify the default from email address. The address will be included on the message sent to the recipient if no overriding sender is supplied to the <GATEWAY EMAIL> command. See also the <GATEWAY EMAIL> command.
[Databases]
Identifies all databases that will be accessed by the Gateway. The location can be specified either as a drive:\directory\databasename or with a UNC naming convention (eg \\server\sharename\path\databasename). The ACCESS database is used to maintain information about the current sessions. You must specify this database. NOTE: This database has nothing to do with Microsoft Access; it is a Concordance database. The CLIENTS database has special meaning to the Gateway program. It can be used as the basis for secure operations. The Clients database structure should contain fieldnames for ALIAS (username), PASSWORD, and optionally one other field containing valid security keywords. The GATEWAY database contains records of databases published by the Gateway system. See the Gateway Build command reference entry for further information. [This function has temporarily been suspended] As for ACCESS specify all other databases that will be searched or accessed by the Gateway. You may use UNC names or specify the drive:\path\database name. If the database fails to open check that the correct path has been specified and that suitable security access is available.
ACCESS={drive:\path\name | \\unc\path\name}
CLIENTS={drive:\path\name | \\unc\path\name}
GATEWAY={drive:\path\name | \\unc\path\name}
LogicalName=physicalName
Page 26 of 93
Browse Parameters
NEXT=value PREV=value DOCNO=number DOCNO=snapshot:query:number Display the next list of results in the current display format file. Display the previous list of results in the current display format file. Start listing at this document number. When the Gateway restores a snapshot it will automatically position the current document to this number. The DOCNO parameter will also accept a secondary format where the value contains the snapshot name, query number and document number. These are normally specified through the use of the <gateway docno format=sqd> command. See also <gateway docno> TIMESTAMP=timestamp Internal number unique to each user or each search. This parameter is added automatically to links and forms as necessary. Switch to this display or processing form. The formName must be the exact name of the file in the forms directory.
DISPLAYFORM=formName
Page 27 of 93
Gateway Commands
All of the Gateway Commands have the format: <GATEWAY COMMAND VARIABLE=VALUE VARIABLE=VALUE > The Gateway Commands can be upper or lower case. Each gateway command must be on a single line - do not split the commands over multiple lines. Gateway commands like Cycle, EndCycle, Include, If, Else, and Endif should be placed on a line of their own, do not code other HTML alongside these commands. Nesting is allowed in most instances, for example all if-else-endif, include processing and the cycle command may be nested indefinitely. Gateway commands may be embedded within other Gateway commands. This allows for example, the easy inclusion of Gateway parameters inside a Gateway link command, as in: <GATEWAY LINK DISPLAYFORM=<GATEWAY PARAMETER NAME=NEXTFORM>>
<GATEWAY APPEND RULES=ruleName> <GATEWAU APPEND RULES=STORE:storename>
The Append command is used to add a record to a database. The "ruleName" refers to a file in the forms directory that specifies the rules for appending the record. The use of the STORE:storename syntax uses a store instead of a file to append the database. It is important that this method is used over the file method when using form libraries. The third form of the command does not require a RULE file, but assume that all of the fields to be written to the new record are parameters prefixed with some predefined text. For example, if the FIELDMATCH value were AF and a parameter called AFID existed, then the value of this parameter will be written to a database field named ID. An example rule file is: blank, requests name, name subject, subject msgtextarea, msg_field subdate, subdate, dmy-ymd append, requests The "blank, logicalDatabaseName" specifies
<GATEWAY APPEND DATABASE=logical FIELDMATCH=prefix UNIQUE=fieldname DATEFORMAT=format SEPARATOR=sep>
Page 28 of 93
the database to which the record will be added. The middle section of the file identifies the "formFieldName, databaseFieldName, options" and may be repeated as often as necessary. The final line in the file, "append, logicalDatabaseName" saves the record. The options field is used to perform special conversion functions prior to the data being written back to the database. Currently the options provide the means of formatting an input date to the Concordance standard YMD format. Use either DMY-YMD or MDY-YMD on your date fields. A further option is valid to merge different parameter values into a single field, by using APPEND=string the text specified will be appended to the named field, along with the value of the parameter. A special string value of nl allows for the parameter value to be appended following a new-line character. You may also add literal text by enclosing it in quotes, in place of the parameter name, for example: Blank, requests Subject, subject Items, message itemlist, message, append=: , message, append=nl From, message, append=nl who, message, append=: append, requests If the field defined is being populated from a multi-value select statement in your HTML form, then there will be multiple values to be imported here. To define this you must add the option SEPARATOR to the specific field. By default a space will be added between each value, although you can specify a separator using the format: SEPARATOR=value. (A space will be appended to the separator
Page 29 of 93
value). The value NL can be used to place each selected entry on a new line, in this instance no space is added to the delimiter. For sites requiring replication facilities there is an additional option on the blank command, making the line: BLANK,logicalName,uniqueField. Similarly there is an update command to use on rule files for updating records: UPDATE,logicalName,uniqueField. To test whether the record was written correctly you may check the STATUS. Status values are OK, FAIL, and CANCEL. See the "IF STATUS" command. <GATEWAY APPENDSTORE NAME=name> This command allows additional information to be appended to an existing store. The store name must exist prior to this command. See also STORE <GATEWAY APPLICATION> The Gateway application command is replaced by the name of the current application. The Gateway application command is replaced with the application type, as specified in the applications registration. The Archive command is used to archive the current record to the named database. It is imperative that the field counts and types match exactly between the current and the named database. You can specify an additional parameter that seeks to ensure that record being archived remains unique in the target database. The value in the fieldname identified by the UNIQUE parameter will be appended with a - followed by the TIMESTAMP. The OVERWRITE parameter is used to overwrite an existing record with a matching key. Instead of simply appending the record a search will be performed first, if an existing record is found it will be overwritten, if no record is found a new record will be generated. The optional RELATED parameter allows a
<GATEWAY APPLICATIONTYPE>
<GATEWAY ARCHIVE DATABASE=logical> additional parameters: UNIQUE=fieldname OVERWRITE=fieldname,fieldname, RELATED=logical
Page 30 of 93
related database to be used for matching of the field counts and types rather than the current database. <GATEWAY AVP ALIAS=alias> additional parameters CLIENTDB=logical The Automatic Verification Process (AVP) can be used to generate a long lasting URL that will provide a user authenticated access into a Gateway application. This facility is excellent for emailing a link to a user. To format the link use the construct: http://<gateway server>/<gateway application>/ gateway/gateway.exe? application=<gateway application>& avp=<gateway avp alias=<gateway field name=alias database=clients highlight=off> clientdb=clients>& displayform= When the Gateway processes the AVP parameter it will automatically apply the clients security to the current session. The Gateway will only process the AVP parameter when a login attempt is made, ie when using a <gateway if user=alias> command. Add the additional parameter, CLIENTDB, to identify the logical database name for the clients information. <GATEWAY BREAK> The BREAK command is used to exit a CYCLE early. The command will cause the current cycle in progress to end when the next ENDCYCLE command is reached. Note: The cycle will not exit immediately, the commands up until the next ENDCYCLE will process normally, then the cycle will end as though it were out of records to process. See also CYCLE <GATEWAY BROWSE> additional parameters: HIGHLIGHT=ON | OFF EMPTIES=ON | OFF DATABASE=logical The Browse command is like a Cycle in that we loop through the HTML following, up to the ENDBROWSE command. Each field is processed in turn during the cycle; the field name and value can be displayed as required. See also the FIELD command. Use the optional parameter HIGHLIGHT to
Page 31 of 93
specify whether you want the search terms highlighted. This option is on by default. Specify the EMPTIES parameter to display all fields, even if they have no value. By default this value is off and empty fields are not displayed. Use the optional DATABASE parameter to identify a database source other than the default. <GATEWAY BTREE LIST=logicalName ADD=key or DELETE=key> additional parameter VALUE=n The logicalName for the list file is identified in the LIST parameter, the logicalName should be present in the [Databases] section of the Gateway.INI file. The key value is the actual text entry obtained from the list file. The optional VALUE=n parameter is used to specify a numeric value when adding a new key to the file. See also, GATEWAY CYCLIST to list entries from the Btree file. <GATEWAY BUILD>
[This command has been temporarily suspended]
Use the BTREE command to add or delete keys from a Btree list file.
Use this command to build gateway forms for the current record in the Gateway database. This will overwrite any existing forms for the named database, be careful. The GATEWAY database is a special database used to store Gateway form definitions that can be appended and modified online (as for any Concordance database), and then default forms built. You must have a GATEWAY database entry in the Gateway.ini file and a GATEWAY.DCB database to use this facility. The default forms (that may be modified as necessary for your installation) are called: Gw.search the search form Gw.list the list form
Page 32 of 93
Gw.full the full form Inside these default forms special replacements take place, a <GW#fieldname> will be replaced by the value of the named field from the Gateway record. An optional subfield may be specified on these commands, for example, <GW#fieldname:2> would be replaced by the second subfield in the named field from the current Gateway record. The subfield can be specified on any of the GW# commands. When processing multiple fields within these forms, for example, a list of fields to display in a list form or full form, you can specify each fieldname (and subfield information) on successive lines. For example: Title term:TITLE Author:AU Subjects:SUBJ In the default forms you will want to cycle through these in a similar manner to the Field Cycle routine. Use the <GW#CYCLE:fieldname>, <GW#ENDCYCLE:fieldname>, and <GW#FIELD:n> commands to cycle through a portion of code using each line of the named field. For example: <table> <GW#CYCLE:SRCHFIELDS> <tr> <td> <b><GW#FIELD:1></b> </td> <td> <input type=textbox size=50 name=SRCHFT<GW#FIELD:2>>
Page 33 of 93
</td> </tr> <GW#ENDCYCLE:SRCHFIELDS> </table> To specify different type of searching you could replace SRCHFT<GW#FIELD:2> with SRCH<GW#FIELD:3><GW#FIELD:2> and place the search type into a third subfield on each line. <GATEWAY CHANGEPASSWORD alias=<username> password=<password>> Use the ChangePassword command to change the password of the specified user to the specified password Use the CopyFile command to copy a file from one location to another. The copy command will automatically overwrite an existing target file is it exists. The filenames are normally relative to the Gateway application virtual directory location. Use the optional SLASH parameter to set all of the slashes in both filenames to forward or backward slashes. The COPYGROUPING command is used to display grouping links for a resources items. These are grouped in Branch and Collection groupings. The data is returned as a semicolon separated list (use a cycfields). The Data is returned comprises the following pieces of data for each grouping. Branch, Collection, Location, Available Copies, Copies, Status, Date Due The TRANSLATE parameter is used to specify a translation form, to be used to translate the statuss. The DISPLAYRESBOXITEM parameter is use to allow resource box items to be included in the groupings. By default this is set to false. If this parameter is set to true any items that belong to a resource box are displayed. <GATEWAY CREATEPOPULARSTATS DATABASE=logical FIELD=fieldname This command is used to create popular and least popular statistical processing data. Using
<GATEWAY COPYFILE FROM=filename TO=filename> additional parameters: SLASH=FORWARD | BACK
<GATEWAY COPYGROUPING TRANSLATE=translateform DISPLAYRESBOXITEM>
Page 34 of 93
SFIELD=field name>
the supplied statistics search result it will take the data from field in statistics (remove quotes if present) and search specified database for SFIELD matching the data. Then increment the number of occurrences in the statistics database for that record. All records should be set to zero prior to starting this process. Cycle Fields is used to control display of subfielded data. You can therefore control the HTML displayed between each sub-field, and at the beginning and end of the list. The function supports multiple fields processing, allowing the first sub-field from the first field to be processed in tandem with the first sub-field from the second field, third field, etc. The separator is one of the following:
<GATEWAY CYCFIELDS FIELDS=fieldname/separator,fieldname/separa tor... SUBFIELD=separator> additional parameters: HIGHLIGHT=OFF COUNT=number
FIELDS=gw#strategy SUBFIELD=strategy
NL
where each entry is on a new line comma separated values semi-colon separator special waitlist delimiter special strategy delimiter
COMMA SEMICOLON
FIELDS=gw#journalclaim SUBFIELD=NL
WAITLIST STRATEGY
COSTCENTRE special costcentre delimiter FIELDS=gw#spelling SUBFIELD=spelling SPELLING special spell-check delimiter
The default separator is the SEMICOLON. Use the optional HIGHLIGHT=OFF parameter to disable search term highlighting. For example:
FIELDS=REG#subkey
FIELDS=STORE:storename
<table> <tr><td>Collection</td> <td>Location</td> <td>Status</td></tr> <GATEWAY CYCFIELDS
Page 35 of 93
FIELDS=collection,location,status SUBFIELD=NL> <tr><td> <GATEWAY GETCYCFIELD FIELD=1> </td><td> <GATEWAY GETCYCFIELD FIELD=2> </td><td> <GATEWAY GETCYCFIELD FIELD=3> </td></tr> <GATEWAY ENDCYCFIELDS> </table> See also ENDCYCFIELDS and GETCYCFIELD. Currently this command cannot be nested. A special instance of the CYCFIELDS command may be used to process the search history from the Access records. Use the FIELDS and SUBFIELD parameters as displayed on the left. You may then unload the various elements from each line of the search history from the current record. The elements are unloaded in order, ie: 1. SEARCH 2. Strategy 3. Operator 4. Snapshot / docno parameter 5. Hits 6. Docs 7. Search time
Page 36 of 93
8. End of line The JournalClaim parameter is used to process a SCHED record. The field value to be cycled is populated by item identifiers or the word BROKEN. The word BROKEN identifies a broken subscription. A special instance of the CYCFIELDS command maybe used to list Gateway entries from the Registry. Use the FIELDS parameter to specify which Registry subkey to list, for example REG#Databases. Use the SUBFIELD=NL option to identify the breakdown of each part. The Gateway supports a spell checking function. This requires a DICTIONARY list file to be included in the list of Database registry entries. The Spell-checker supports the use of additional parameters, FIELDNAMES=storeName (the store will contain a list of fieldnames, one per line) which identifies the fields to be checked, START=docno:fieldname:offset (where the spell checking will begin from), and IGNORENUMBERS={true|false} which indicates whether words beginning with numeric values will be checked this is off by default. It is also possible to use a Store as the source of the data to be subfielded, use any Subfield parameter as required. When you retrieve values with the GETCYCFIELD command you will get firstly the value followed by the data entry. The cycle will continue until all entries are processed. <GATEWAY CYCLE COUNT=n> additional codes: DIRECTION=LIFO START=n START=BOTTOM DATABASE=logical The Cycle command is the primary point at which the system supports the display of multiple records. The Cycle command must have a matching ENDCYCLE command. Each document in the result set is passed across the HTML commands between the Cycle and EndCycle statements. The Cycle command may be nested to any level, allowing the internal Cycle to process before each of the outer Cycles. This is useful when cycling through the records in a related
Page 37 of 93
NAME=logicalName OPTION=optionValue
database. Note: When cycling a related database, the RELATE command must be outside of all nested cycles (ie the database must be open before the cycling starts). The documents displayed will be the lesser of the result set tally or the value of the COUNT parameter. If COUNT=30 and there are 50 records then 30 documents will be displayed. If COUNT=30 and there are 10 records then 10 documents will be displayed. The DIRECTION parameter is optional. It has one valid parameter, LIFO, allowing the system to display the documents in reverse order; the display will begin from the end of the database. You can optionally specify a start document using the START code. This is useful when going to a specific document in the result set or writing pages for reporting. The special keyword BOTTOM can be used to start at the last document. This is useful to begin the display with the last document in the database. Use the DATABASE parameter to specify an alternative database to cycle. This is useful for listing data from a related database following a lookup. You may optionally specify a name for this Cycle. This has no effect on the output. The OPTION parameter allows the specification of additional CYCLE processing options. The current options are: NOTAGS do not perform any tag processing with this cycle.
See also BREAK <GATEWAY CYCLETAGS additional codes: DATABASE=logical SELECT=ALL | CURRENT | NOTCURRENT Use the optional DATABASE parameter to specify an alternative database. Use the optional SELECT parameter to indicate which global tags to list. ALL specifies that all global tags from the named database are to be cycled. CURRENT indicates only global tags Use the CYCLETAGS command to cycle through the global tags in the current database.
Page 38 of 93
specified on the current record should be cycled. NOTCURRENT indicates all global tags except those applied to the current record. The default value is ALL. See also the TAGENTRY and ENDCYCLETAGS commands. <GATEWAY CYCLIST NAME=logicalName COUNT=n> The Cyclist command is used to list values from a B-tree file, for example an authority list file (*.LST) as used in Concordance. Each Cyclist command should have a corresponding ENDCYCLIST command. The list file should be included in the Databases section of the Registry or Gateway.ini file and assigned a unique logical name. The logical name is then specified in the Cyclist command. The Count parameter specifies how many entries to list. The default value is 1. The additional Start parameter may be used to begin listing entries from the specified value. For example: <gateway cyclist name=subjhead count=30 start=d> will begin listing from entries beginning with D. Currently this command cannot be nested. See also the LISTENTRY command. <GATEWAY DATABASE> This command is replaced with the file name of the current database, excluding any path information and file extension. Eg LIBRARY This command is replaced with a list of the current databases used in the current search. Normally this display is used in the Search Results form. This basic format of this command is replaced by todays date, formatted with the default format (DMY). The FORMAT parameter is used to indicate the date display format, those currently available are: DMY for DD/MM/YYYY, MDY for MM/DD/YYYY, YMD for YYYYMMDD, HMS for HH:MM:SS, and DMYHM for DD/MM/YYYY HH:MM.
additional codes: START=value
<GATEWAY DATABASES>
<GATEWAY DATE> <GATEWAY DATE FORMAT=fmt ADJUST=num> additional parameters: VALUE=yyyymmdd
Page 39 of 93
The ADJUST parameter is used to adjust todays date by adding or subtracting num days. If the number is negative it will be subtracted from todays date, if it is positive it will be added. The additional VALUE parameter may be used to override the use of todays date, instead specifying a specific date value to be adjusted, formatted and displayed. <GATEWAY DEBUG VALUE=on | off> The debug command can be used to turn the debugging system on and off. With debug on the Gateway will generate a gateway.log file in the temp-folder, containing debug information that may be helpful in solving a problem. The Delete command deletes the current document. If the current document is deleted the status value will be set to OK, else it will be set to FAIL. Use the IF STATUS command to test whether the deletion was successful. Use the IF DELETED command to test if a record is already deleted of not. The optional DATABASE parameter is used to specify the database from which the current document should be deleted. The optional UNIQUE parameter can be used to identify the fields that would comprise a unique key this is used where you want a replicatable transaction to be generated. The optional FILE parameter can be used to delete a file. Check if the file exists first using the <gateway if file=filename> command. The success of the deletion can be tested by check the Gateway status value, OK or FAIL are the values. <GATEWAY DISPLAYFORM> <GATEWAY DISPLAYFORM NAME=formName> The first format is replaced by the name of the current display form. The second format will update the current display form name to the specified value. This is useful prior to specifying document links. For example the current form may be a SUMMARY listing 30 documents at a time. Use this command to specify a FULL format form, following by the LINK command on each document. When the link is taken the system will redisplay the chosen document using the
<GATEWAY DELETE> Additional parameters: DATABASE=logical UNIQUE=fieldname, FILE=filename
Page 40 of 93
FULL format. When a link or form is specified, the Gateway will automatically add various parameters, one of these parameters will be a Displayform, and the value used will by default be the same form as is currently being processed. Use the DISPLAYFORM NAME=name to modify the default form used in generated links and forms. See also the LINK command; consider using DISPLAYFORM and a parameter here. <GATEWAY DOCNO> <GATEWAY DOCNO FORMAT=SQD> This second format allows the reference to the Snapshot file, the current query number, and the current document. This is an absolute reference to a particular document and allows the Gateway to support the use of the Back and Forward buttons. The Format options, S Q and D, can be specified individually, however normally they are used together. The default value for Format is D. S refers to the snapshot file name. Q refers to the query number. D refers to the document number. When strung together colons : separate the data elements. Use the optional DATABASE parameter to specify an alternative database in use. Use the ADJUST parameter to display the next or previous document numbers. Use the MAX parameter to specify the maximum value when using an adjust. I.e. adjust=20 will display a value equal to the current document number + 20, however if there are only 15 documents then MAX=15 will only allow the display value to reach 15. <GATEWAY DOCS> Is replaced by the total number of documents in Is replaced by the current document number relative to the result set.
additional parameters: DATABASE=logical ADJUST=n MAX=m
Page 41 of 93
additional parameters: DATABASE=logical
the current result set. Use the optional DATABASE parameter to identify the specified database. This will usually be the result of a LOOKUP command. The DUPCHECK function is used to check for duplicate records. To use the function you must start with a search result, sort this into the order of the field/fields you are checking. Place the field/fields into a store and then run this command. The Gateway will tag any records identified as duplicates with the named tag. The field/fields should be separated with newline characters in the store, that is, place each field on a newline.
<GATEWAY DUPCHECK FIELDS=storename TAGNAME=text>
<GATEWAY ELSE> <GATEWAY EMAIL ADDRESS=emailAddress CC=ccAddressList SUBJECT=parameter CONTENT=parameter>
See IF Use the EMAIL command to send an email to the specified address. The ADDRESS, CC and SUBJECT parameters can identify either parameter names passed to this invocation of the Gateway, or specific values. The ADDRESS parameter is a semicolon separated list of valid email addresses. The CC parameter is optional, and is also a semicolon separated list. The CONTENT identifies the parameter containing the email body text, or alternatively the name of a store that contains the text to send. Refer to the SMTP registry or initialization section for further information about the delivery of the emails. Use the optional SENDER parameter to override the default sender specified in the SMTP section of the Gateway Registry entries. This can be set to indicate that the content of the email contains HTML markup language. If this is set, the email will be sent with a ContentType of text/html. Without it set, the default of text/plain will be used.
Optional parameters: SENDER=emailAddress
HTMLEMAIL=true ATTACHNAME=name ATTACHCONTENTS=storeName ATTACHFILES=fileNameList
Page 42 of 93
CONTENT-TYPE=type
Use the optional ATTACHNAME parameter to specify the name to be used for a single file attachment. This must be used together with the ATTACHCONTENTS parameter which is used to specify the name of the store which contains the contents of the attachment. Use the optional ATTACHFILES parameter to specify a list of files to be attached to the email. The list should be separated by the pipe character e.g. ATTACHFILES=directory/fileName1 | directory/fileName2. Files that do not exist are ignored. Use the optional CONTENT-TYPE parameter to specify the content-type that will appear in the email header. The default is plain/text. An example alternative is plain/xml.
<GATEWAY ENDBROWSE> <GATEWAY ENDCYCFIELDS> <GATEWAY ENDCYCLE> <GATEWAY ENDCYCLETAGS> <GATEWAY ENDCYCLIST> <GATEWAY ENDIF> <GATEWAY ENDSTORE> <GATEWAY EXEC COMMAND=cmd> Optional parameters: SLASH=BACK | FORWARD WAIT=n STARTIN=directory
See BROWSE See CYCFIELDS See CYCLE See CYCLETAGS See CYCLIST See IF See STORE Executes the named command on the Web server machine. The end-user has no control over the command executed; it is controlled entirely from the form. If the program is successful then the STATUS value is set to OK, otherwise the STATUS will contain the return code. By using the SLASH parameter you can force the Gateway to translate all forward slashes to backward slashes, or vice versa. Use SLASH=BACK or SLASH=FORWARD to define the desired direction of all slashes in the command line. The Gateway will by default wait for 10 seconds for the program to complete. If the program takes longer than 10 seconds then the
Page 43 of 93
Gateway will return a default value of -1 and continue on, leaving the process to run to completion. Use the WAIT parameter to specify how many seconds the Gateway should wait for completion. If 0 then the Gateway does not wait to see if the program completed, the program is left to continue processing and the Gateway will continue processing the form. Output from commands will be lost unless written to a file and then displayed using an include command. The standard input, output and error are not inheritable. <GATEWAY EXCLUSIVE ACTION=LOCK | UNLOCK> optional parameters: DATABASE=logical This command will attempt to lock the database for exclusive use, or unlock the database after exclusive use has completed. Use this command if you are wanting to pack or zap a database, or require exclusive access for a specific function. That function must take place in the current Gateway execution, once the Gateway finishes processing the database will be closed and the lock automatically released. Use the optional DATABASE parameter to specify a database other then the default. The status value will be set to: OK, NOT LOCKED, or NOT UNLOCKED. <GATEWAY FIELD NAME=44ieldname> <GATEWAY FIELD NAME=44ieldname LOCK=fieldName2> <GATEWAY FIELD NAME=44ieldname TRANSLATE=translateForm> <GATEWAY FIELD NAME=44ieldname DATABASE=logicalName> To display the contents of a database field. There are many various parameters regarding the display of a field value, these are described below. The basic format of the FIELD command, is to display the content of the field in its entirety. Paragraph fields will automatically have the search terms highlighted. Dates are automatically formatted to a long text format. Numbers are displayed as numeric values. Use the LOCK parameter to place a lock on the record so that the user can update the value. fieldName2 is the name of a special field in the database being updated where the users timestamp will be written no other users will be allowed to update this record while a valid timestamp exists. By convention
additional codes: FORMAT=formatStyle
Page 44 of 93
FORMAT=COUNTLINES FORMAT=COUNTCHARS FORMAT=DATE FORMAT=ISBN FORMAT=NAME FORMAT=TRANSLATE FORMAT=FORMALNAME FORMAT=URLENCODE FORMAT=HTML2ASCII FORMAT=HTML2TEXTAREA FORMAT=NOWRAP FORMAT=NEWLINE2EOL FORMAT=ESCAPE HIGHLIGHT=OFF SUBSTR=AnLn | AnCn | spineX CONTEXT=n SUPPRESS=REPEAT STRIPCHARS=string
a fieldname2 is usually called LOCK, hence LOCK=LOCK. The contents of 45ieldname are returned as in the first form of the command. Use the TRANSLATE parameter to specify a translation table on the values in this field. This translation table function can be used to display descriptions of codes etc. See TRANSLATEFORM for more information. Use the DATABASE parameter to specify that this field is retrieved from a related database. Specify the logical database name and the fieldname from this database. All codes are compatible with this form. By default the Gateway interface will assume that the data coming from Concordance is preformatted, exchanging carriage returns for <BR> html commands. To override this process use the FORMAT=WRAP command. Use the FORMAT=TEXTAREA option for placing paragraph text into textarea boxes. TEXTAREA formatted fields will also pickup the TRANSLATE option below. For dates the Gateway will automatically format a long format date, Month DD, YYYY. To format a date for updating (i.e. into a DD/MM/YYYY or MM/DD/YYYY format) then use FORMAT=DATE or FORMAT=MDY or FORMAT=DMY and the HIGHLIGHT=OFF parameter. Where fields contain text and a date, the date will still be formatted. The first 8 consecutive digits are assumed to be the date, leading or trailing text will be unaltered. To display the number of lines or characters that make up a field, use the FORMAT=COUNTxxxxx option to replace the content with the appropriate count. Use FORMAT=ISBN where you need a valid 10 or 13 digit ISBN with no punctuation (digits only). If the field does not contain a valid ISBN, an empty string is returned. When using the Gateway BROWSE command you can display the name of the field using the FORMAT=NAME parameter. To extract the value from a field during a BROWSE command, specify all of the normal FIELD options but do not specify the NAME
Page 45 of 93
parameter. For example: <Gateway field format=name> The Translate format will automatically replace HTML special characters with their HTML representations. The characters currently translated are: & < & < >
For Concordance fields containing a persons name, you can use the FORMALNAME option to formalise the name layout. This option will format names as below: Mark John Sanders Sanders, Mark John Mark Sanders Sanders, Mark M J Sanders M J Sanders M Sanders M Sanders
Use FORMAT=URLENCODE if you need to encode special characters inside a URL. Use FORMAT=HTML2ASCII to replace <br> with ASCII newline characters. This is relevant when you have formatted HTML data to write to a file. Translates <br> to \r\n. Use FORMAT=HTML2TEXTAREA to replace <br> with a single newline character, suitable for use within a textarea. Translates <br> to \n. Use FORMAT=NOWRAP to retain HTML breaks and newline characters. Translates all \r or \n or \r\n to <br>\n. Use FORMAT=ESCAPE for the string to be returned with a leading \ before any double quotes for use in javascript. By default the Gateway interface will always highlight search terms where possible. If highlighting is not required use the
Page 46 of 93
HIGHLIGHT=OFF command. You should avoid using highlighting when placing field values into text boxes and text areas for updating. You should also avoid highlighting when placing field values into search strategies. When using multi-line (formatted) fields you can use the SUBSTR code to extract selected lines. The An code defines how many lines to skip, i.e. After 0 lines. The Ln code specified how many lines to return. For example, A0L1 will return the first line of the field only. When using AnCx characters are used instead of lines in the above explanation. The SPINEX value will format the string into X number of lines for display on spine labels. The option STRIPCHARS parameter allows a string of characters to be specified to be stripped from the end of the string. It continues to strip characters until the string is empty of the last character is not in the stripchars string. The optional CONTEXT parameter allows the client to see the search terms in context of a long paragraph. n is the number of words or blank lines to display either side of the actual terms. This is particularly useful in large full text documents. The SUPPRESS option will suppress printing of this field if the value is the same as the last time this field was displayed. That is, the first time you use this fieldname in a gateway field name=fieldname command it will save the value, the second time (if the value is the same) it will display nothing. It will continue to display nothing until a different value is available. When updating see UPDATE. When using related database see RELATE. Displaying URLs: The Gateway field display will automatically display URLs as hypertext links. If the field contains the text http:// or https:// or ftp:// or telnet:// then the text up to the next blank is considered to be the URL and will be
Page 47 of 93
automatically formatted as a clickable link. If the text <a href= is found in the field then the auto-link feature is disabled for the display of this field. If the HIGHLIGHT=OFF parameter is used on the Gateway command then this feature is disabled. Generally highlighted terms within the URL will not affect the auto-link feature (allowing you to search for the company URL), however this is not the case if the highlighting affects the continuity of the http:// text string. <GATEWAY FILENAME filepath=filepath_name extension=extension> Replaced with the name and extension of the first file matching the description. Filepath_name should not include the extension. Extension can use * wildcard. Can include or exclude the . In the extension. Replaced with the size of the file, with b, kb or mb after the number depending on its size. If UNITS=NONE is an optional parameter no units are appended and the size is in bytes
<GATEWAY FILESIZE FILE=fname> Optional parameters: UNITS=NONE <GATEWAY FORM variable=value > Optional parameters: NAME=htmlFormName ENCTYPE=MULTIPART/FORM-DATA
The FORM command is replaced with the standard HTML <FORM> statement, and semi-completed to re-execute the current Gateway CGI program on the current server and application. There will be a number of standard hidden variables appended to the end of the form command that will help the Gateway to process a continued session. You must code the close form HTML statement to complete the form, that is, </FORM>, following the form input controls. Add as many additional parameters to the Gateway form command as necessary, these will automatically be included in the generated form as hidden type input fields. If you using any JavaScript you will want to specify a NAME=htmlFormName parameter so that you can reference the elements of the form. If you wish to upload files to your web server
Page 48 of 93
using the Gateway, then you must use the additional parameter ENCTYPE and also be using a request-method of POST (see the Registry or Gateway.ini file settings at the beginning of this document). The uploaded file is given a name corresponding to the session timestamp and a file count, e.g. 02511034521.1, and stored in the Gateway temporary directory (refer to the Registry or Gateway.ini file for the TEMP location). You can process the uploaded file in the following Gateway form by referring to the parameter name <gateway parameter name=filenameX.local> where X is replaced by the count of the files being uploaded. Normally X will be 1 if only one file is being uploaded. Sample code might be: <gateway form enctype=multipart/form-data displayform=saveUpload> Enter name of upload file: <input type=file name=filename> <input type=submit value=Send> </form> <GATEWAY FORMFOLDER> Is replaced by the path to the form folder. This is useful when using the Gateway write or file commands. See also TEMPFOLDER. <GATEWAY FORMLIBRARY> Is replaced with the formlibrary name and path being used for this session of the gateway. Is replaced by the language being used by the forms library for this session of the gateway. Retrieve the next sub-field value from the fields prepared at the beginning of the CYCFIELDS command. num is the relative field number, 1 is the first field specified, 2 the second, etc. At each call the next sub-field will be returned. Sub-field separator is defined in the
<GATEWAY FORMLANGUAGE>
<GATEWAY GETCYCFIELD FIELD=num> optional parameters: TRANSLATE=translateForm FORMAT=formatString
Page 49 of 93
CYCFIELDS command. Use the TRANSLATE parameter for translation of entries using a translation form. See TRANSLATEFORM for more information on translation. Optionally you may include the FORMAT string with the GETCYCFIELDS command to modify the output format of the selected text. See FIELD command for more information on available formats. See CYCFIELDS and ENDCYCFIELDS. <GATEWAY GLOBAL FIELD=fieldname FROM=fromValue TO=toValue> Perform a global change on the current database, changing all occurrences of fromValue to toValue within the named field. Use the optional DATABASE parameter to specify a database other than the default. Use the optional FROMFLAG in place of the FROM parameter to specify one of the options, AnyValue (meaning change from any value), or NoValue (meaning change from an empty field with no current value). Use the optional TOFLAG in place of the TO parameter to specify the option NoValue (meaning make this field blank). The optional COUNT parameter can be used to limit the number of changes that are made. The optional LOCATION value indicates the offset to begin making changes in the first record of the result set. Successive records will begin from an offset value of 1. This function is used in combination with the COUNT parameter during spell checking to replace a single instance of a word. <GATEWAY GOTO DOCNO=num DATABASE=databaseName> optional parameter: DOCNO=snapshot:query:num Use the optional DOCNO value of snapshot:query:number to move to a particular snapshot result (not the current result set). The snapshot file should exist before you use this parameter. Move to a particular document number within the current result set.
Optional parameters: DATABASE=logical FROMFLAG=ANYVALUE | NOVALUE TOFLAG=NOVALUE COUNT=number LOCATION=offset
Page 50 of 93
<GATEWAY GWX gwxparm=gwxvalue>
Use the GWX command to setup various values for the Gateway Extension plugin. The plugin is used to communicate with other Windows applications running on the web client. Typically this is used for functions such as Word Export reporting or communicating with local devices such as label writers. For example: <gateway gwx name=gwx value=comment> <gateway gwx name=pluginver value=> <gateway gwx name=file value=> <gateway gwx name=mode value=> <gateway gwx name=export value=>
<GATEWAY HITS>
Is replaced by the total number of hits in the current result set. The IF, ELSE, and ENDIF statements form the basis for conditional processing. If the condition evaluates to true, then the HTML statements following the IF will be processed, up to the first ELSE or ENDIF statement. If the condition evaluates to false, then the HTML statements following the IF will not be processed. If an ELSE statement occurs then the condition reverses up to the ENDIF statement. Normal processing of HTML continues after the ENDIF. The Gateway program fully supports nesting of IF statements to any level. See the following entries for specific tests that can be made regarding the data and content.
<GATEWAY IF condition> <GATEWAY ELSE> <GATEWAY ENDIF>
<GATEWAY IF APPLICATION=appname>
Returns true if the application being run is the same as the applied appname. Returns true if the application registration indicates it is the correct application type. Supported application modes are: Oliver, Liberty3, E-Reference, Gateway.
<GATEWAY IF APPLICATIONTYPE=apptype>
<GATEWAY IF BROWSER=browserString>
Returns true if the browser string is contained
Page 51 of 93
in the text identifying the browser http-useragent, else it returns false. For Internet Explorer the text msie may be used. For Netscape Navigator the text netscape may be used. For Macintosh browsers you may specify mac. <GATEWAY IF CHANGEPASSWORD= <expiry_days> alias=<username> Use this command to see if the user requires their password to be changed. If the date in the PWCHANGED field in the borrower database is outside the expiry days variable this function returns true indicating the password has expired. Check if the current document comes from the named database. The name tested here is the name of the physical database, not the logical name. Checks if the current record in the named database is deleted. If no database is identified then the command will check the current document in the current default database. For example: <gateway if deleted=> will test the current document in the default database. <GATEWAY IF DOC=FIRST> <GATEWAY IF DOC=LAST> additional parameters: DATABASE=logical <GATEWAY IF EXCLUSIVE=default | logical> Test if we have exclusive access available to the named database. To test the default database specify the name default. Exclusive access implies that we are the only user to have the database open at this point in time. Use this exclusivity test prior to performing online operations such as packing or zapping, either of which would fail if exclusive access were not available. Add the database parameter to specify a database other than the current default database. Simple tests for the first and last documents in a result set.
<GATEWAY IF DATABASE=databaseName>
<GATEWAY IF DELETED=databaseName>
Page 52 of 93
<GATEWAY IF EXPIRY=number of days>
If the registration for this application is going to expire within the specified timeframe (in days) this returns true. No affect on registrations without an expiry date. The first format supports testing if the field exists and has some value (any value). A date value must not be 00/00/0000. The second form tests the value of the data in the field based on the listed condition testers. Conditional tests are: VALUE=value tests the value of the field to match the specified value. Mainly used to compare text values. This test is case insensitive. CONTAINS=value tests if the database field value contains the specified value. This test is case insensitive. STARTSWITH=value tests if the database field value starts with the specified value. This test is case insensitive. GT=num | date compares a numeric or date value against the named database field. LT=num | date compares a numeric or date value against the named database field. GA=string greater than or equal to, alphanumeric comparison (strcmp) LA=string less than or equal to, alphanumeric comparison (strcmp) EQ=num | date compares a numeric or date value against the named database field. Use the optional DATABASE parameter to identify that the field specified comes from the named target database. To test a date field use GT, LT, or EQ. Optionally you may specify the value as TODAY(n) where n is the number of days to add or subtract from todays date. Optionally you can specify an additional parameter as in TODAY(n,s) where s is the date style, for
<GATEWAY IF FIELD=fieldName> <GATEWAY IF FIELD=fieldName condition=value> <GATEWAY IF FIELD=fieldName DATABASE=databaseName>
SCOPE=ANY | ALL | SOME | NONE SEPARATOR=NL | COMMA | SEMI | SPACE FIELD=specialCode FIELD=fieldSpecialCode SECURITYMATRIX=matrixname
Page 53 of 93
example, DMY, MDY, or YMD the date style should match the style for the database field. For example TODAY(0,DMY) is todays date as D/M/Y. TODAY(-7,YMD) is the date 7 days previous to today in a Y/M/D format. For fields that contain multiple values, and you want to test combinations of these values, you can use the SCOPE and SEPARATOR parameters. The SCOPE identifies how many matches should be found and the SEPARATOR dictates how the field is broken into values. Special codes: In addition to specifying a valid fieldname, you can also specify some special gateway values to test. These are: GW#DOCS which is the total number of documents, GW#DOCNO which is the current document number, and GW#DOCNOODD which tests whether the document number is odd or even. You may test literal values using the VALUE#value format. This is most useful when using an embedded Gateway command, as in the following example: <gateway if field=VALUE#<gateway total name=amount function=PRINT%1.2f> gt=0> You may also test Registry keys and values, using the format REG#registryKey. If you are using a Gateway.INI file in place of the Registry entries, then values will be checked in the Gateway.INI file. Field special codes: You can test the size of a field by requesting a field special code. Current codes are: LINECOUNT#fieldname and CHARCOUNT#fieldname. Replace fieldname with the name of the field to be sized. The content then being tested is the count value rather than the field value. Security matrix: The security matrix option is designed to work with a hierarchical security system, where access to information is refused or granted
Page 54 of 93
based on a series of matrix entries for each logged in user. A sample command might be: <gateway if field=code securitymatrix=view> In your application security field (copied from the clients database when you signed on to the application) you would have some value like: VIEW(A,D,P) The above if condition would return true if the value in the CODE field on the current record began with A, D or P. Otherwise it would return false. An application can have multiple matrices operating in one application, for example: VIEW(A,D,P) UPDATE(A-300,D) Might allow view access to codes beginning A, D, or P while update access was only available for codes beginning A-300 or D. See IF USER for more information about security. <GATEWAY IF FILE=filename> Returns true if the named file exists, else return false. This is useful for testing the existence of forms to be called. Use this command to test the IP address of the incoming request. This is useful if you want to provide additional security to your internal users versus the external access to your Gateway interface. You may use partial IP addresses if you wish, for example, <GATEWAY IF IP=192.168> will match successfully with any IP address beginning as such. <GATEWAY IF ISVALIDSFX=fieldname> Verifies if the fieldname contains data for a valid SFX link. Currently only ISSN and ISBN are supported. Returns true if your alias is found in the Circulation List field of the current Journal. Otherwise return false.
<GATEWAY IF IP=ip-Address>
<GATEWAY IF LIBERTY=CIRCLIST> optional parameters
Page 55 of 93
DATABASE=logical ALIAS=alias USERNAME=alias
Use the optional DATABASE parameter to specify a database logical other than the default. The database specified should be Sched. Specify the ALIAS to test. If this parameter is not specified the Gateway will use the USERNAME parameter. If neither of these parameters are specified the currently signed on users alias will be used. Returns true if your alias is found in the Contents Page field of the current Journal. Otherwise return false. Use the optional DATABASE parameter to specify a database logical other than the default. The database specified should be Sched. Specify the ALIAS to test. If this parameter is not specified the Gateway will use the USERNAME parameter. If neither of these parameters are specified the currently signed on users alias will be used. Returns true if your alias is found in the Notify list of the current Journal. Otherwise return false. Use the optional DATABASE parameter to specify a database logical other than the default. The database specified should be Sched. Specify the ALIAS to test. If this parameter is not specified the Gateway will use the USERNAME parameter. If neither of these parameters are specified the currently signed on users alias will be used. Special Liberty/Oliver condition that checks if the on-loan item is valid for Renewal. If any waitlist exists or the maximum number of renewals has been exceeded this test will return false, else true. For multi-branch libraries you may specify the optional SATISFY=fieldname parameter to identify the ISSUES field used in the waitlist satisfaction area. This applies to reserves that can only be satisfied by particular copies of an item, normally this will be the BRANCH code
<GATEWAY IF LIBERTY=CONTENTSPAGE> optional parameters DATABASE=logical ALIAS=alias USERNAME=alias
<GATEWAY IF LIBERTY=NOTIFY> optional parameters DATABASE=logical ALIAS=alias USERNAME=alias
<GATEWAY IF LIBERTY=RENEW> optional parameters MAXRENEWALS=n WAITLIST=NONE SATISFY=fieldname
Page 56 of 93
DATABASE=logical ALIAS=alias USERNAME=alias
(the default value) however it can also be the BARCODE if you are using copy specific wait listing. You must have the ISSUES database related in this form for this function to work. The Waitlist database must also be available in the gateway.ini file. Use the optional DATABASE parameter to specify a database logical other than the default. The database specified should be Sched. Specify the ALIAS to test. If this parameter is not specified the Gateway will use the USERNAME parameter. If neither of these parameters are specified the currently signed on users alias will be used.
<GATEWAY IF LIBERTY=RESERVED> optional parameters DATABASE=logical ALIAS=alias USERNAME=alias
Special Liberty/Oliver condition that checks if the current user is on the Wait-list for this item. You must have the ISSUES database related in this form for this function to work. The Waitlist database must also be available in the databases section of the Registry or Gateway.INI file. Use the optional DATABASE parameter to specify a database logical other than the default. The database specified should be Sched. Specify the ALIAS to test. If this parameter is not specified the Gateway will use the USERNAME parameter. If neither of these parameters are specified the currently signed on users alias will be used.
<GATEWAY IF LIBERTYSTATUS=status>
Returns true if the status specified is contained within the Status value on the current item record. The default database must be the Issues database. This function tests the last lookup (see LOOKUP) on the predefined Related database (see RELATE). If one or more records are found then the command returns true, else false. If NOSAVE is a parameter with any value, the
<GATEWAY IF LOOKUP=logicalDatabase> optional parameters: NOSAVE=value
Page 57 of 93
lookup will not do a snapshot. If a snapshot is not required, this will greatly improve performance and reduce memory requirements which can be important inside large CYCLEs. <GATEWAY IF PARAMETER=paramName> optional parameters: VALUE=value CONTAINS=value EXACT=value Test the value of an HTTP parameter. Without any additional parameters this basic test checks if the parameter is valid and has any value. Use the VALUE parameter to check a specific value. Use the CONTAINS parameter to check if the value is contained in the current parameter value. paramName is the name of the parameter, and value is the value to which it will be compared. The comparison is case insensitive and only as long as the value string. Use the EXACT parameter to perform an exact match check on the parameter and value. This check is case insensitive and length insensitive. <GATEWAY IF REGISTEREDMODULES=value> Test the value of the modules part of the registration key being used. The modules part is the fifth to eight characters inclusive (ie the second block of 4 characters) of the registration key as well as any extended registered modules. These appear in the registration key between -X-, and are appended on to the original 4 modules with a separator when matching. Use a question mark to mean any character. For example if you wish to check that the last character of the original registration modules string is an S, and the first 2 characters of the extended modules are FR, use value=???S-FR??. The current use of this is: ?Q?? ??N? ???S ????-J ????-S ????-P Quest Network File Indexing Syndetics Oliver Junior Oliver Standard Oliver Professional
Page 58 of 93
????-A ????-?P ????-??S ????-???F ????-????-S ????-????-? A ????-????-? ?Z ????-????-? ??O ????-????-? ???-E ????-????-? ???-?S <GATEWAY IF REGISTEREDMENUMODULE=value>
Oliver Advanced Picture Search Screen Capture (mediaCam) Fingerprint support Item Submission Audit Trail
eZy Cataloguing
Ollie OPAC (to include in Liberty registrations) Exclude Ollie (to remove from Oliver registrations) Sip2
Test if a particular menu module is enabled; value will be a string value such as "Articles" or "Class Loans". The tables below show how this relates to the Registration key. The gateway command <GATEWAY IF REGISTEREDMENUMODULE =value> will only return true if both the menu module and its parent are considered to be ON. ON means that the character at the index position in the menu modules part of the registration key is not 0, or that the Absent flag is set to true.
menuModules array list ItemName Cataloguing
Articles
MARC Definitions
Modify Forms MARC Editing MARC Export Resource Boxes Archive
Index 0 8 9 10 11 12 13 22
ParentIndex 0 0 0 0 0 0 0 0
Absent 1 1 1 1 1 1 1 1
Page 59 of 93
Binders Circulation SDI Class Loans Charges Self Issue Serials Journals Indexing Acquisitions EDI Inter Library Loans
System Custom Forms Custom Reports Translations
23 1 14 15 16 24 2 17 3 18 4 5 19 20 21
0 1 1 1 1 1 2 2 3 3 4 5 5 5 5
1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
The above table maps to the menu modules part of the registration key as follows:
0 1 2 3 4 5 6 Reserved for future use 7 Reserved for future use 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
Circulation Serials
Acquisitions Inter Library Loans
Articles
MARC Definitions Modify Forms
MARC Editing MARC Export Resource Boxes SDI Class Loans Charges Journals Indexing EDI Custom Forms Custom Reports
Translations
Cataloguing
Binders
Archive
Self Issue
eZy Cataloguing
Reserved for future use
The menu modules part of the registration is recognised in the registration key because it is prefixed and postfixed by '-M-'. For example in the key: O123-0000-1212-X-JYRW-L-X-M-MHTW-00PW-M-61BF-7EC7 The menu modules part is: MHTW-00PW Here are some example keys, along with the key features of what is and is not enabled: Key O123-0000-1212-1234-5678 Key Features Application type Licenses Expiry Modules Menu Modules Description Application type Licenses Expiry Modules Oliver 123 12/20012 None None Traditional short key. All menu modules are enabled. Oliver 123 12/20012 Quest and Oliver Junior
O123-0Q00-1212-X-J-X-M0000-0000-A000-0RSC0000-00-M-1234-5678
Page 60 of 93
System
Menu Modules O123-0Q00-1212-X-J-X-M0000-0000-1000-0111-000000-M-1234-5678 Description Application type Licenses Expiry Modules Menu Modules Description
L333-00NS-1220-M-CCSA0S-M-1234-5678
Application type Licenses Expiry Modules Menu Modules Description
Only Articles, Resource Boxes, SDI and Class Loans are enabled. New extended registration key. Oliver 123 12/20012 Quest and Oliver Junior Only Articles, Resource Boxes, SDI and Class Loans are enabled. This is the same as above but 1s have been used to indicate turned on modules. This works just as well but is less intuitive. Liberty3 333 12/20020 Network File Indexing and Syndetics Everything apart from ILL. No product has yet been defined with these features; however this could be done with no code changes. This command is used to secure certain functions for access by 61ieldname61 users. During username / password validation a designated field can be copied from the client database to the session database. This process precludes having to lookup the client record every time we want to check the security. See IF USER=fieldname. This command will then test if the security value specified is contained within this field. In some cases, a space separated list is supplied in the SECURITY parameter. If ANY is set to TRUE in such a case, any word in the list is searched for in the SECURITY field. For example: We may have a field on the client record containing security information, such as, UPDATEBALANCE ALLOWRESERVES SYSTEMACCESS. Each of these codes may be tested before access is granted to the area or function within the application. To test whether the code is valid use the following: <gateway if security=ALLOWRESERVES> See also IF USER=VALID
<GATEWAY IF SECURITY=value> optional parameters: ANY=TRUE/FALSE
<GATEWAY IF STATUS=value>
This command is used to test the return status of certain commands. Currently the values that
Page 61 of 93
can be tested are ok, fail, and cancel, although other values may be valid for specific functions. Functions that return a status include APPEND, UPDATE, EMAIL, EXEC, EXCLUSIVE, ARCHIVE, GLOBAL, DELETE, RECALL, REGISTRY. <GATEWAY IF STORE=storename> Returns TRUE if the named store currently exists and is available for appending or processing. Test whether the current document is tagged with the named tag. If the GLOBALNAME parameter is specified then the Gateway will look for a tag with the specified name. For example, GLOBALNAME=label new item. If the NAME parameter is specified, then the Gateway will look for a local user tag, normally these tag names are shorter, for example NAME=REQ. Use the optional DATABASE parameter to specify an alternative to the default database. The TAGSUPPORT command must be called prior to this test being performed <GATEWAY IF USER=62ieldname> optional parameters: SECURITY=securityField BYPASS=PASSWORD CLIENTDB=dbLogical Performs the verification on the username / password combination (when they are passed). Once the username and password are verified they are no longer passed as parameters therefore this process is only valid once to establish a user authenticated session. Note: The use of this command assumes that 2 parameters have been passed to the Gateway, USERNAME and PASSWORD. If these 2 parameters are not passed the authentication will not happen. The value from the USERNAME parameter is searched against the named field, fieldName, normally this will be the ALIAS field, in the BORROWER database, using a relational search, for example: where the value of the USERNAME parameter is TOMCAT and the 62ieldname is ALIAS, then ALIAS = TOMCAT (i.e. the ALIAS field should be keyed for best performance).
<GATEWAY IF TAGGED=null {NAME=ext | GLOBALTAG=name}> optional parameters: DATABASE=logical
<GATEWAY IF USER=VALID>
Page 62 of 93
For authentication to be successful: 1. The borrower record must be located. 2. The value of the PASSWORD parameter must match exactly the value in the PASSWORD field. Note: these tests are case insensitive. If the authentication was successful then the HTML following this condition is executed, if unsuccessful then the HTML following the ELSE statement will be executed. The optional SECURITY parameter can be used to load a set of security keywords into the session database, refer to IF SECURITY=xxx. The designated security fieldname in the borrower database is copied to the SECURITY field in the session database for later conditional processing. You must have a SECURITY field in the session database for this facility to work. The optional BYPASS=PASSWORD parameter can be used in an authenticated environment, this precludes the need to compare the password value with that held in the borrower database. The optional CLIENTDB parameter can be used to specify an alternate borrower database. The default borrower database will be referenced by the logical name BORROWER. The final form of the command, IF USER=VALID, simply tests if the current user has been authenticated. If your login name is not the value in your ALIAS field in the borrower database, then you will use the syntax: <GATEWAY IF USER=loginField> However you will also require the ALIAS for other search strategies to operate. To do this add a field called ALIAS to your session database, the content of an ALIAS field in the borrower database will be automatically
Page 63 of 93
populated to the session database field when the user is authenticated. <GATEWAY IF USERNAME=value> Tests whether the current username is the same as that specified. Allows for specific user processing options. Similar to the html include commands include the named form at this location in the generated output. This command can be used at any point in the form, however it must be the only command on the line. Use the NAME format of this command to process the named form file, or use the FIELD parameter to identify the include data to come from the named field. Use the optional DATABASE parameter to obtain the data from an alternate database other than the current one. You may nest includes to any desired level. <GATEWAY INCLUDE FIELD=64ieldname> optional parameters: DATABASE=logical variable=value STATIC=on You can specify a third form name using the BRANCHNAME parameter. If this third form exists then it will be used in preference to all others. The BRANCHNAME parameter is ignored if the DisableLocalNames registry option is on. You may optionally include other parameters that can be used as desired for substitution within the included file. For example: <GATEWAY INCLUDE NAME=xx CODE=ab> The included file accesses the parameter value using the following format: <!-- %GATEWAY NAME=var In our example above the code <!-%GATEWAY NAME=CODE would be You can specify a second form name using the LOCALNAME parameter. If this second form exists then it will be used in place of the first named form. This parameter is useful for providing a local override to the standard forms shipped with your Gateway application. The LOCALNAME parameter is ignored if the DisableLocalNames registry option is on.
<GATEWAY INCLUDE NAME=formName> optional parameters: LOCALNAME=formName BRANCHNAME=formName variable=value STATIC=on
Page 64 of 93
replaced by ab. Substitution is performed on each line from the input form prior to any other Gateway command being processed, this allows substitution to be embedded inside other Gateway commands where necessary. The variables are cascaded down the nested chain of includes, so a parameter specified at the first include is still available 7 nests lower! Is that useful or what? Use the STATIC parameter to avoid any Gateway processing when sending the content of a form to web browser. Normally Gateway commands are processed before sending, the STATIC parameter will disable all Gateway processing on the file specified for including. <GATEWAY LASTPAGE CYCLESIZE=<cyclesize>> Used to calculate the document number that would be the start of the last page. It is designed so that each page prior to the last one is a full cycle size, and that only the remainder are displayed on the last page. These are special entries for use with the Liberty/Oliver library management system. The Name parameter identifies the special function name. NAME=BIBTYPE For a given bibtype, this will return the name of the bibtype. This is provided for performance reasons as this will only access the DB the first time that it is called for a given gateway. NAME=STATUS Status=Single to display the status of a catalogue item. The function will attempt to provide a single entry indicting the best status among all copies, that is, if any AVAILABLE then report Available, or the alternate text for Available. If none available but some are OUT then report On-loan, or the alternate text for Out. Status=Test tests the status value, see IF LIBERTY=STATUS NAME=ISSUE
<GATEWAY LIBERTY NAME=function>
<GATEWAY LIBERTY NAME=BIBTYPE BIBTYPE=string
<GATEWAY LIBERTY NAME=STATUS STATUS=SINGLE STATUS=BRANCHES STATUS=TEST LIMIT=collection-code(s) AVAILABLE=text OUT=text>
Page 65 of 93
<GATEWAY LIBERTY NAME=ISSUE ALIAS=borrowerCode DAYS=14|parameterName>
You must be cycling the ISSUES database to use this command. The current ISSUES record will be issued to the borrower code identified in the ALIAS parameter. You must also specify a loan period using the DAYS parameter. This can specify a specific value (number of days) or a parameterName that contains the overriding due date. NAME=RENEW Renew the selected item. DAYS=n allows renewal period to be specified. If this is not specified the renewal will be for the same period, from todays date. In addition to the number of days you can also specify the name of a parameter that is included in the form, this parameter will contain a date value that may override the default value calculated. CHARGE=d1,c1,d2,c2, - specify the charges to apply on renewals if they are late. d1 is the number of days after which the first charge is applied; the charge is c1. For example: CHARGE=7,1.00,14,2.50 would equate to a $1 charge when the item is 7 days overdue and a $2.50 charge when the item is 14 days overdue. NAME=RETURN
<GATEWAY LIBERTY NAME=RENEW> additional codes DAYS=14|parameterName CHARGE=d1,c1,d2,c2,
<GATEWAY LIBERTY NAME=RETURN>
<GATEWAY LIBERTY NAME=RESERVE> additional codes LIST=COUNT LIST=REMOVE ALIAS=borrowerCode
You must be cycling the LEND database to use this command. The current item will be returned if it is on loan. <GATEWAY LIBERTY NAME=CIRCLIST> additional codes LIST=ADD|REMOVE ALIAS=alias NAME=RESERVE Reserve the selected item. By default the command will add the current user to the Wait list for this item, unless they are already on the list. Optionally you may specify the LIST=REMOVE code to remove the user from the Wait list or LIST=COUNT to display the total number of reservations against this item. The user to add to the waitlist is by default the
<GATEWAY LIBERTY NAME=CONTENTSPAGE>
Page 66 of 93
additional codes LIST=ADD|REMOVE ALIAS=alias
currently signed on user. If the ALIAS parameter is specified it will use this ALIAS in preference to the signed on user. NAME=CIRCLIST Add your name to the circulation list for this journal. If there is a controlled circulation list your name will go on the end of this list, else it will be added to the end of the last copy circulation list. If no current list exists it will create a list for COPY-1 and place your name on this. Use LIST=REMOVE to remove your current entry. The optional parameter ALIAS can be used to specify a user other than the currently signed on user. NAME=CONTENTSPAGE Add your name to the contents page list for this journal. Your name is added to the end of the list to receive your own photocopy of the contents page. For example, the text appended to the field is: COPY CP=SMITHJ Where SMITHJ is the current users alias. Use LIST=REMOVE to remove your current entry. The optional parameter ALIAS can be used to specify a user other than the currently signed on user. NAME=NOTIFY
<GATEWAY LIBERTY NAME=NOTIFY> additional codes LIST=ADD|REMOVE ALIAS=alias
<GATEWAY LIBERTY NAME=CHARGE AMOUNT=n.nn DESC=descriptive text>
<GATEWAY LIBERTY NAME=CHANGEALIAS FROM=oldAlias TO=newAlias>
<GATEWAY LIBERTY NAME=CHANGEBARCODE FROM=oldBarcode TO=newBarcode>
Add your name to the e-mail notification list for this journal. Your name is added to the top of the current list of notifications. Use LIST=REMOVE to remove your current entry. The optional parameter ALIAS can be used to specify a user other than the currently signed on user. NAME=CHARGE Used to generate an ad-hoc charge to a client.
<GATEWAY LIBERTY NAME=PARAMETER RECORD=recordValue SOURCE=nameValue>
Page 67 of 93
<GATEWAY LIBERTY NAME=SPECIALBARCODE DATEBASE=logical>
Specify the amount of charge as n.nn and the descriptive reason as descriptive text. You must set up a Gateway relate command to open the CLIENTS database prior to using this command, and you must also be looking at the current Client to be charged. NAME=CHANGEALIAS Used to change the alias of a borrower. Specify the from and to parameters of the old and new alias. The system assumes you have checked the values are correct and valid alias. Databases affected: BORROWER, LEND, LENDSTAT, WAITLIST, SCHED, CLNTCHRG, SDI, ORDERS, ORDREC, INLN, INLNSTAT. The status is set to OK or FAIL during this command. NAME=CHANGEBARCODE Used to change the barcode of an item. Specify the from and to parameters of the old and new barcode. The system assumes you have checked the values are correct and valid barcodes. Databases affected: ISSUES, LEND, LENDSTAT, CLNTCHRG, INLN, INLNSTAT. The status is set to OK or FAIL during this command. NAME=PARAMETER Use this option to retrieve a parameter value from the Liberty database. The RECORD and SOURCE parameters are used to construct the search that identifies the record. For example: RECORD=FDCKEY SOURCE=usercode_f5 will generate RECORD = FDCKEY AND NAME = usercode_f5 NAME=SPECIALBARCODE Use this option to perform special barcode processing on the specified database using the
Page 68 of 93
supplied data set. The process will cycle through the record set, first looking for a record in the ISSUES database with a BARCODE the same as the data in the specified databases BARCODE field. If the BARCODE is not found, it is rearranged using the SpecialBarcodeformula15 parameters and the search is performed again. If a match is located the ISSUE record is renumbered to the new BARCODE. The Formula format is: CHARACTER;POSITION;X+X+Y+Y+X+X+ X+X+X+Y, where: CHARACTER is the identifier used to match the formula with a barcode. This must be one character long POSITION is the base-1 index location that CHARACTER must be in for a barcode to match the formula X is a character placeholder for index location X in the barcode Y is a String literal enclosed in single quotes An example formula using the above format might be: M;4;1+2+'6'+'M'+5+6+7+8+'I' Spaces are only allowed around the plus symbols (ie not around CHARACTER or POSITION)
<GATEWAY LINK variable=value >
Is replaced by the Gateway CGI program name and a list of current parameters necessary to maintain consistency within the session. You can specify different or additional parameters to be included using the variable=value format. If one of these additional parameters specified is the same as one of the current parameters, the additional parameter is used in preference. For example: <a href=<gateway link displayform=abc>> Link-text </a>
<GATEWAY LISTENTRY> optional parameters: FORMAT=formatOptions
This retrieves the current value from the LIST file currently being processed. This command is only valid within a CYCLIST command. Use the FORMAT parameter to specify different output formats (as for GATEWAY
Page 69 of 93
TRANSLATE=translateTable
FIELD). Use the TRANSLATE parameter to identify a translation table to display this value.
<GATEWAY LOAD FILE=filename> optional parameters: DATEFORMAT=dateFormat DELIMITERS=delimiterOption DATABASE=logical FIELDORDER=storeName
Loads the named CSV file to the current default database only. It wont work on a related database. The CSV format will assume comma separated fields, records separated by newlines, and quotes surrounding fields that have embedded commas and special characters. The date format will default to your installation setting. The field order in the database is reset immediately prior to the load being processed, so the CSV input format must match the underlying database structure. To adjust the order add each fieldname to a store, one fieldname per line, to identify the field order in the CSV input file. Specify the name of this store in the FIELDORDER parameter. Use the optional DATEFORMAT parameter to specify the format of the dates being loaded. Valid values are: DMY, MDY, YMD. By default the system will use your installation date setting, unless Concordance delimiters are specified, then the format is automatically switched to the international date format (YMD). Use the delimiter option to define which delimiters are used within the CSV file. The default option is CSV, using the comma, double quote, and new line character, (44,34,13). Another option is CONCORDANCE, where the Concordance standard characters are used, (20,254,174). . Use ALTERNATEQUOTES if your was UNLOADED using this. This is used where data may contain standard double quotes followed by a comma, which causes problems with CSV files. ALTERNATEQUOTES causes the ` character to be used as a quote in the CSV file.
<GATEWAY LOOKUP DATABASE=logical>
Performs a search against a related database, the strategy as defined in the previous RELATE command. The Lookup function creates a temporary
Page 70 of 93
result; it does not create a snapshot. Therefore you cannot use a GATEWAY DOCNO command to refer to this result. See also the RELATE command. <GATEWAY MARCIMPORT FILE=file> optional parameters: OVERWRITELIBRARY=true | false OVERWRITEISSUE=true | false MARC records are initially loaded to the MARCTEMP database to ensure that the MARC file is actually valid. Once complete the records are then checked for matches in the existing catalogue (based on ISBN / ISSN searching) and if found and the OverWriteLibrary parameter has a value of true then they are updated in place, otherwise a new record is created. Create a display copy of the current MARC21 record. If the record does not exist in the catalogue then create it as necessary. If a FORCEDBIBTYPE is passed, this is used as the bibtype regardless of any tags or GMDs in the MARC record. Create a MARC21 record from the current display / catalogue record. Generate a MARC21 file of the current result set of catalogue records. The gateway will replace this command with a 32 character upper case hexadecimal MD5 checksum string of the concatenated inputs. The order of each component of the input string is always as shown regardless of what order they appear in the command. UTCDATE=TRUE will include the UTC date in the format YYYYMMDD in the input string. UTCTIME=TRUE will include the UTC time in the format HHMM in the input string. RegistrationName=TRUE will include the registration name in the input string. RegistrationCode=TRUE will include the Import the named MARC21 file to the Liberty/Oliver catalogue.
<GATEWAY MARC2CAT> optional parameters: FORCEDBIBTYPE
<GATEWAY MARCRETRO>
<GATEWAY MARCEXPORT>
<GATEWAY MD5CHECKSUM optional parameters: UTCDATE=TRUE/FALSE UTCTIME=TRUE/FALSE RegistrationName=TRUE/FALSE RegistrationCode=TRUE/FALSE InstallUID=TRUE/FALSE MD5Parm1=Value
Page 71 of 93
MD5Parm9=Value
registration code in the input string. InstallUID=TRUE will include the Install Unique ID in the input string. MD5Parmn=Value will include the Value as part of the input string where n can be from 1 to 9. After this command, the parameter UTCDATEUsed will hold the value used in the input string. After this command, the parameter UTCTIMEUsed will hold the value used in the input string. After this command, the parameter md5Input will hold the entire input string used, this is intended for debugging purposes. For example at 01:03 AM on 15 Oct 2007 the command: <gateway md5checksum md5parm9='Goodbye World!' md5parm1='Hello World!' UTCDATE=TRUE UTCTIME=TRUE > will produce: E8AFB7880C9AAF9F9E8D28D37ED0B888 Where the input string was 200709150103Hello World!Goodbye World!
<GATEWAY MOVEFILE FROM=filename TO=filename> optional parameters: SLASH=FORWARD | BACK <GATEWAY MULTILINECHANGE FIELD=field to change
Moves the named from file to the named to file. Use the optional SLASH parameter to automatically standardize all separators to the same direction. See also FILE, TEMPFOLDER, FORMFOLDER This command is tailored for fields that contain multiple identifies on separate lines (eg CIRCLIST in the SCHED database). You should be cycling the database you wish to
Page 72 of 93
optional parameters FROM=from value TO=to value DATABASE=database to change
update. One record at a time is updated. The process works by splitting the existing data on new line characters. Each line is then compared to the from value and processed based on the to value. Matches have the text replaced with the to value (blank will remove it), while non matches are not changed. The field parameter is the only mandatory field, however a blank from parameter will not result in any changes being made. A blank 2 field will result in matching values being removed.
<GATEWAY NEXT> additional parameters: DATABASE=logical <GATEWAY NUMGEN SOURCE=sourceValue FORMAT=format> optional parameters: DATABASE=logical
Moves the current document pointer to the next document. This way you can process 2 documents within a CYCLE command. Use the Database parameter to specify the related database to which the command refers. Provides for automatic generation of unique numbers from the Liberty database. NUMGEN will lookup a specific record in the Liberty database, located as RECORD = PARAMETER AND NAME = sourceValue, and when found the value in the DATA is the last used value. The number will be incremented and then saved into the record and also returned to replace the Gateway command. The optional FORMAT parameter can be used to modify the format of the generated number. A string of 9s will generate a zero padded number up to the length of the string. An @ in the string is replaced with the current year (4 digits). Any other character is retained in place. I.e. @-9999 might be replaced as 19990024. For example: <input type=text name=ID value=<gateway numgen source=libraryId()>> or <input type=text name=ORDER_NO value=<gateway numgen source=73ieldna() format=@-99999>>
Page 73 of 93
Use the optional DATABASE parameter to specify a database name other than LIBERTY. See also the APPEND command. You can specify an option in the rules file to generate a unique number. <GATEWAY OPEN DATABASE=logical> Closes the current default database and opens the named database as the current default database. See also the DATABASE parameter this is the normal method of specifying a default database. <GATEWAY PACK> optional parameters: DATABASE=logical Pack the current database. You must only have the database open once. If there is any error performing the pack a return code message will be displayed back to the user. Optional add the DATABASE parameter to specify an alternate target. See also EXCLUSIVE and IF EXCLUSIVE. <GATEWAY PARAMETER NAME=parameterName> additional parameters: FORMAT=formatStyle GWX=wordexport | excelexport Displays the value of the named parameter. The parameter is retrieved from those being passed to the cgi program, or those in the session database. You can also specify the optional FORMAT and GWX parameters that will affect the way the value is displayed to the user. Refer to GATEWAY FIELD FORMAT=formatStyle for further information on the format styles that are available. Is replaced by the HTML previously stored under the same Store Name. Use the optional FORMAT and GWX parameters that will affect the way the content is displayed to the user. See also STORE, FIELD FORMAT=style. Retrieves the protocol that is being used for this session. This will normally be https:// or http://. This value is derived from the information passed to the gateway by the web
<GATEWAY PRINT NAME=storeName> optional parameters: FORMAT=formatStyle GWX=wordexport | excelexport <GATEWAY PROTOCOL>
Page 74 of 93
server. <GATEWAY PURGETEMPFILES> MINUTES=number Deletes all files in the gateway temp directory older than the number of minutes specified. MINUTES is optional, the default is 120. Note, files that are locked, secured against the gateway process or in use may not be deleted. Generate a range of links to the current result set. For example, 1-20 21-40 41-60 Use the QLDATABASE parameter to identify the source database for the results. Use the QLBLOCK parameter to identify either the number of records to group or the keyword YEAR. If the value is set to 50 then the resulting links would be 1-50 51-100 etc. If you specify YEAR you also need to specify the QLDATEFIELD parameter to identify a date field where the year will be extracted. The default value of QLBLOCK is 10. Each group of records will generate a URL link to display these, based on the document numbers specified. To include a snapshot and query, pass this value in the optional QLDOCNO parameter. Use the TARGET parameter to identify the HTML target value, for example to open a new browser window. Use the CLASS parameter to add a class= element to the link. <GATEWAY RECALL> additional parameters: DATABASE=logical Optionally specify the database to which this recall should apply. Use the IF STATUS command to check whether the RECALL was successful. Use the IF DELETED command to check if the record is deleted prior to recalling it. <GATEWAY REGISTRY SECTION=sectionName Retrieves the current value of the named variable within the named section. All section names are relative to the Gateway\ApplicationRecalls the currently deleted record from the default database.
<GATEWAY QUICKLINK QLDATABASE=logical QLBLOCK=number | YEAR QLDATEFIELD=fieldname QLDOCNO=docno TARGET=targetValue> CLASS=classValue>
Page 75 of 93
VAR=variableName> optional parameters: VAL=value
Name key. Use a null section value to retrieve a variable from the Gateway root key. Optionally specify the VAL parameter to set the current value of the named variable. To test is the value was set use the GATEWAY IF STATUS=OK command. Update access to the registry is controlled by Windows security. See also the GATEWAY CYCFIELDS command which will loop through the entries in a registry key.
<GATEWAY RELATE DATABASE=logical SOURCE=fieldname | STORE:store TARGET=76fieldname>
Setup a related database. The two databases must each have a field that contains an identical value. There may be multiple documents in either database. This command will open the database(s) in readiness for lookups. Specify the logical database name (or comma separated names) of the related database in the DATABASE parameter. Specify the local fieldname in the SOURCE parameter and the related fieldname in the TARGET parameter, or enter a store name using the STORE:name format. Use the store option when the link can not be achieved by a standard comparison between two fields, for example where you need to add further search qualifiers. You must specify a RELATE command prior to any LOOKUP commands. See also UNRELATE.
<GATEWAY RELOAD>
The Reload command is use to instruct the Forms Library to reload all forms. Only the currently active forms library will reload. To reload all languages each will need to issue the reload command. The Replicate command is used to create a number of new copies that are an exact match to the current copy, except the barcode. The Issues database must be currently on the record to be replicated. The BARCODES parameter is a list of barcodes for the new copies. The list of barcodes determines the number of copies to be created. Each barcode
<GATEWAY REPLICATE BARCODES=barcodes BARCODEDELIMITOR=delimiter
Page 76 of 93
FIELDS=fields FIELDSDELIMITOR=delimiter Optional parameters COPYNUMBER=copynumber LIMITOUTPUT =0|1
is separated by the string in the BARCODEDELIMITOR parameter. The Fields parameter lists the fields that are to be replicated, only the fields listed will be replicated to the new copies. The list of fields is separated by the string contained in the FIELDSDELIMITOR parameter. The COPYNUMBER parameter can be used to specify a starting copy number to be applied to the copies. This will increment for all copies. If LIMITOUTPUT is set to 0 (default), output is produced for this command as usual. If set to anything other than 0, output such as The following copies were successfully created: is omitted.
<GATEWAY RESETSUPPRESS NAME=name>
When using multiple cycles within one form, it may be necessary to reset the Suppressed field between each cycle to ensure the correct result. Name is the fieldname being suppressed. See also FIELD NAME=name SUPPRESS=REPEAT.
<GATEWAY RETRIEVE > TEXTBOX=name CHECKBOX=name SELECT=name optional parameters DEFAULT=value
The Retrieve command is used to recall previous search form values when redisplaying a search form screen. Only the previously used values can be recalled. Note: You must pass a parameter called SAVEFORM to save the contents of the current search form. E.g. <input type=hidden name=SAVEFORM value=xxx> Specify TEXTBOX=77ieldname and the previous value of the named textbox will replace this gateway command. The CHECKBOX command will be replaced by a blank or the word CHECKED as required by the HTML. To specify the appropriate checkbox, use the name and the value in the format NAME_VALUE. For example: CHECKBOX=DATABASE_LIBRARY To retrieve a Select value, use a similar format to the Checkbox layout, using both the select field name and the select value. For example:
Page 77 of 93
SELECT=OPERATOR_AND Use the DEFAULT parameter to specify a default value. <GATEWAY SEARCH SRCHxxField=value> optional parameters: DATABASE=logical Perform an immediate search of the current default database. You may use all of the standard SRCHxxField parameters specified in the parameter section of this document. Your current result set will be lost as soon as you perform this search. You may use this command immediately following an OPEN DATABASE command to perform a predefined search strategy. Use the optional DATABASE parameter to search a related database. <GATEWAY SERVER> This command is replaced by the name of the current server. Allows the Gateway to set a session variable during processing. The created parameter will appear as a parameter variable and value. If a parameter of the same name already exists it will be replaced. If the session variable name matches a field name in the session database then the value will be stored for reference in future executions of the current session. Use the <GATEWAY IF PARAMETER=field1 VALUE=value1> to test the session variable. <GATEWAY SFXLINK [GENRE=genre] FIELDNAME=fieldname This command creates a valid SFX link using the supplied fieldname and some other fields. The GENRE field allows genre specific information to be included in the link to narrow the search. Supported genres are: article, preprint, proceeding, bookitem, book, journal, conference The generated link conforms to the OpenURL specification. <GATEWAY SORT SORT=field> This command allows results to be resorted after the search is completed, particularly with regard to sorting tagged documents prior to
<GATEWAY SESSION NAME=field1 VALUE=value1>
Page 78 of 93
Optional parameters: CUSTOMSORT=field MAXSORT=x DATABASE=logical
download. Specify up to 5 fields. Use the optional MAXSORT parameter to override the default sort limit set in the Registry or Gateway.INI file. x can be any value. Use the DATABASE parameter to specify a related database to sort. To sort in descending order, use field_desc in place of the field. Use the CUSTOMSORT parameter in place of SORT parameter to utilize the special sorting options. Special options exist for: TITLE, LEADTERM, FILENO, LOCATION.
<GATEWAY STATUS>
Displays the current value of the internal status variable. See also IF STATUS=.
<GATEWAY STOP>
Stop all of the CGI processing. Process no further gateway commands or lines from the source HTML file. This effectively ends all output. For example: <gateway if user=valid> <gateway else> Username / Password combination is not valid. Please refer to your IT department<br> </body> </html> <gateway stop> <gateway endif>
<GATEWAY STORE NAME=storeName>
Process the following HTML statements and store the output in memory for later use. The store can be used with various other Gateway commands. In its simplest form the
Page 79 of 93
Gateway Print command can be used to output the store to the user (ie the web page). The contents of the store can also be used for searching with the Gateway Relate command, writing the content of a file with the Gateway Write command, and setting the field processing order with the Gateway Load and Unload commands. The store command is necessary when processing a Search form if you intend to display search terms and strategy information in your resulting page. Place Gateway Store and Endstore commands around the search strategy output, during the processing of the page use the Gateway Print command to display this information at the appropriate location. The storeName can be any valid name. Use a unique name for each store being used inside a form. For example, use different names each piece of static HTML being saved for output. Use different store names for each relate command requiring this facility. A store is only valid once. Once a store has been Printed or Looked up etc, it is no longer valid and any attempt to locate it will result in an a null result. If you attempt to Print a store that does not exist, there will be no output. Use the Gateway Appendstore command to append information to an existing store. See also ENDSTORE, APPENDSTORE. <GATEWAY TAG NAME=ext | GLOBALTAG=name TAG=ON | OFF > Optional: DATABASE=logical Use the TAG command to immediately tag or untag the current document. If the tag is a user local tag specify the tag extension in the NAME parameter. If the tag is a global tag specify the full name in the GLOBALTAG parameter. Optionally you may tag a document from a specific database using the DATABASE parameter. You must have previously defined the tag for use in the form. See the TAGSUPPORT command. <GATEWAY TAGBOX This code is replaced with a "Checkbox" input field named after the value of "ext" or name.
Page 80 of 93
NAME=ext | GLOBALTAG=name > Optional:
Use this code to add checkboxes to your records for selective processing. For example: <gateway tagbox name=req>
CHECKED=TRUE might be used for processing requests for an individual user ie a user specific tag. Use the optional CHECKED parameter to have this box ticked by default. Without the CHECKED parameter the box will only appear checked if the record is tagged with the named tag. It is important to note that the "ext" should not exceed 9 characters in length. This value is used as part of the tag-name on the record. The name value can be any global tag name, and you may have embedded spaces, however you should also enclose the name in quotes. Avoid using quotes inside the tag name. This statement must be preceeded by a TAGSUPPORT statement. The system will automatically apply a tick to a previously selected record. No tick indicates the record is not currently tagged. <GATEWAY TAGDROP GLOBALTAG=name> Additional parameters: DATABASE=logical <GATEWAY TAGENTRY> Additional parameters: DATABASE=logical FORMAT=formatStyle Display the current global tag name. This command can only be used within a CYCLETAGS, each iteration of the loop will present a different tag name. Use the optional DATABASE parameter to specify a database other than the default. Use the optional FORMAT parameter to identify a formatting option. See FIELD FORMAT=formatStyle for a list of styles. See also CYCLETAGS. Removes entirely the named global tag. Use the optional DATABASE parameter to specify a database other than the default.
Page 81 of 93
<GATEWAY TAGRESULT NAME=ext | GLOBALTAG=name > Additional parameters: DATABASE=logical
This code generates a search result of the named tag list. The system will create a new search result based on the records tagged against the "ext" or name taglist. The "ext" entry should not exceed 9 characters. The name value should be an existing global tag name. Use the optional DATABASE parameter to specify a database other than the default. This statement must be preceeded by a TAGSUPPORT statement. The search result generated can be processed normally using any standard Gateway commands.
<GATEWAY TAGSUPPORT NAME=ext | GLOBALTAG=name> optional parameters: TAGCLEAR=ALL DATABASE=logical
This statement builds the support for record tagging used throughout the Gateway. Before you use any other tagging commands you must specify this command. This command will Open or Create the necessary tagfile. Use the NAME parameter to define a tag local to the current user. Use the GLOBALTAG parameter to define a system wide tag group. You may have multiple taglists operational at one time, use different "ext" and name values for each, i.e. REQ (request), RES (reserve), REN (renew), etc. The ext (or Extension) value must be no longer than 9 characters. The name (used in Global tags) may contain embedded spaces but must be enclosed in quotes. Avoid using quotes in the tag name. Using the TAGCLEAR parameter will remove all of the current tags from the named list and any other currently supported tag lists. That is, if you setup tagsupport name=aaa and tagsupport name=bbb tagclear=all, this latter command will remove all tags for both aaa and bbb during setup. Records tagged during the remainder of the form will operate normally. Use the DATABASE parameter to define the tag as being present in a related database.
<GATEWAY TALLY NAME1=name
The TALLY command can be used to tally the
Page 82 of 93
NAME2=name NAME3=name> Additional parameters: DATABASE=logical SUBTOTAL=fieldname
number of records with matching field values. This is useful when producing statistical output. It is important that the current search result is sorted into NAME1, NAME2, and NAME3 order prior to using the Tally command. Up to 3 separate fields can be specified for grouping the output, specify these using NAME1, NAME2, and NAME3. The output from the tally command includes sets of 5 items, the first item is a numeric flag indicating which grouping is being subtotaled, the following three items are the tally field values being totaled (some of these may be blank depending on which subtotal is being written), and the final item is the subtotal tally. The simplest method of processing this output is to store it, and then use CYCFIELDS FIELDS=store:storeName to loop through each iteration of data. The following example demonstrates this principle. Note style0, style1, style2 etc are defined in the cascading style sheet. <gateway store name=ty> <gateway tally name1=fld1 name2=fld2 name3=fld3> <gateway endstore> <gateway cycfields fields=store:ty subfield=nl> <tr class=style<gateway getcycfield field=1>> <td> <gateway getcycfield field=1> </td> <td> <gateway getcycfield field=1> </td> <td> <gateway getcycfield field=1> </td> <td align=right> <gateway getcycfield field=1> </td> </tr> <gateway endcycfields> If the Subtotal parameter is supplied it is assumed the field is a numeric field. A subtotal is produced from the named field for each grouping. This subtotal is output in an extra column.
<GATEWAY TEMPFOLDER>
Is replaced by the path to the temporary file
Page 83 of 93
folder used by the Gateway. This is useful when writing out files with the gateway write command. See also FORMFOLDER <GATEWAY TERMRESULTS> optional parameters DISPLAY=FOUND | NOTFOUND | ALL Is replaced by the individual results for each term in the search strategy that had valid database hits. That is, the default value for the DISPLAY parameter is FOUND. To display terms not located use the optional DISPLAY=NOTFOUND parameter. To display all terms use the optional DISPLAY=ALL parameter. If the parameter ALWAYSRESULTS was set to true and the gateway broadened the search results, the broadened search phrase is returned by this command. This command is only valid when a search has been performed, therefore it is best specified within a SearchForm. <GATEWAY TIMESTAMP> Is replaced by the current value of the TimeStamp. The Total function allows for totaling of values from Concordance records during a cycle (the total is not maintained across pages). You must use the SETUP function to initialise the value for the named total. The NAME of the total field will normally equate to the Concordance fieldname to be totaled, but this is not necessary. To output the total you can use the print function. The print command can be simply PRINT, or you can include printf style formatting on the end, for example PRINT %10.2f is actually the default value. The format of the printed number is controlled by the %x.yf where x is the total number of characters, and y is the number of digits after the decimal point (you must include the % and the f as is). Refer to printf documentation for other options. Following the setup you may use functions of ADD, SUBTRACT, MULTIPLY, DIVIDE,
<GATEWAY TOTAL NAME=fieldname > FUNCTION=SETUP FUNCTION=printCommand FUNCTION=function
Optional parameters VALUE=value DATABASE=logicalName FIELDNAME=fieldName
Page 84 of 93
VALUE, and COSTCENTRE to modify your current total. The value in the named field in the current record will be used in the equation. The VALUE function initialises the current value from the VALUE parameter. The COSTCENTRE function will apply a percentage, a fraction, or replace a value as required for Liberty/Oliver costcentre processing. You may use an optional VALUE parameter to specify the value, this overrides the value from the named field. During a SETUP the value becomes the initialised value. During processing the named field can be retrieved from a related database using the optional DATABASE parameter. Overriding fieldname (incase NAME is not the fieldname to process). <GATEWAY TRANSLATEFORM NAME=formName> The TranslateForm command sets up a translation table for use later in the form. The translation will map a fields data to a predefined replacement text before being sent to the screen. The translationForm is a text file in the Forms directory. Each line defines one translation. The "from" and "to" parts of the translation are separated by a carrot "^", for example: SF^Student Full-time SP^Student Part-time FAC^Faculty IL^Interloan Any fields not matched in the translation table will be displayed "as is". <GATEWAY TRANSMITFILE FILE=filename ResourceID=RID> This commands causes the context-type of the return data to be changed to application/octetstream. This requires that the link to this command specify the contexttype parameter of NO_CONTEXT_TYPE. The file is then transmitted to the browser in binary form. This then allows the client computer to treat the file depending on the file type (opening an image browser, word etc).
Page 85 of 93
<GATEWAY TRANSMITIMAGE FILE=filename>
The commands causes the context-type of the return data to be changed to image/jpeg. This requires that the link to this command specify the contexttype parameter to NO_CONTEXT_TYPE. The image is then transmitted to the browser in binary form. No text can be included in the display, only the binary image. Reduces the current result set to just the records that have unique values in the named fields. Unload the current result set to the named file in a CSV format. By default all fields will be unloaded in the order they are defined in the database structure. Override this by specifying a list of fields, in the order required, in a store and identify the storename using the optional FIELDORDER parameter. To specify a database other than the default, use the optional DATABASE parameter. By default the output will be formatted use standard CSV delimiters, specify the optional DELIMITERS parameter to override this. Use ALTERNATEQUOTES if your data may contain standard double quotes followed by a comma, which causes problems with CSV files. ALTERNATEQUOTES causes the ` character to be used as a quote in the CSV file. By default the exported date format will be set to the installation default. If the delimiter parameter is set to Concordance then the default date format will be YMD.
<GATEWAY UNIQUE FIELD=name,name>
<GATEWAY UNLOAD FILE=filename> optional parameters: DATABASE=logical FIELDORDER=storeName DELIMITERS=CSV | Concordance | ALTERNATEQUOTES DATEFORMAT=ymd | mdy | dmy | std
<GATEWAY UNRELATE DATABASE=logical>
Databases opened using the RELATE command can be closed by using this UNRELATE command. The database is identified by name. The Update command is used to update the contents of the specified fields on the current record. The "ruleName" refers to a file in the forms directory that specifies the rules for updating the record. The use of the STORE:storename syntax uses a store instead of a file for updating the database. It is important this technique is used when using
<GATEWAY UPDATE RULES=ruleName> <GATEWAY UPDATE RULES=STORE:storename> <GATEWAY UPDATE FIELDMATCH=prefix
Page 86 of 93
DATABASE=logical UNIQUE=fieldName DATEFORMAT=format SEPARATOR=sep>
form libraries. An example rule file is: name,name subject,subject msgtextarea,msg_field A shortened version of the update command can also be used, this form does not require a RULES file, however it assumes that all parameters are prefixed with a set value, and that the remaining parameter name is the same as the field to be updated in the database. See APPEND for a sample of the FIELDMATCH syntax. In all cases the record must be locked using the "FIELD LOCK=field" command prior to being updated - see FIELD. If the record is not locked the update will fail. If the record is already locked you will get an alert message indicating some other user has the record locked. For definitions of the options for formatting field values before they are stored in the database, see the APPEND command. For sites requiring replication facilities there is an additional initial line that can be added to this rule file: the update command is used on rule files for updating records. Add the following line as the first in the rule file: UPDATE,logicalName,uniqueField. To test whether the record was written correctly you may check the STATUS. See the "IF STATUS" command.
<GATEWAY UPDATEWEBSTATS ResourceID=RID>
This call should be used to indicate a website has been viewed, and increase the statistics as if it has been circulated. Uses the transaction files. The RID is the Resource Identifier from the Library database. Output the content of the named store to a text file named fname. The named file is created is it doesnt already exist. If the file does exist it will be overwritten. This command may be used to create dynamic forms during normal operation. This allows you to build a store over multiple lines and then have these lines all wrap
<GATEWAY WRITE FILE=fname STORE=ab> optional parameters: NL=BR NL=NONE MODE=APPEND
Page 87 of 93
together. By default, new lines and blanks will be retained in the output file. By using the NL=BR option all new line characters will be removed, and the <br> operator will be replaced by a new line character. The NL=NONE option removes leading and trailing new line characters. This is necessary when writing a gateway tally store to a file that can then be loaded to a database using gateway load. This command should not be used when using form libraries, as creating the file (or modifying) will cause all forms to be reloaded into the library. APPEND and UPDATE now support rules coming directly from stores. If MODE=APPEND is used, instead of creating a new file, it will append to an existing file if it exists. <GATEWAY ZAP DATABASE=logical> Zap the named database. This operation will remove all current records from the database. The database must be open via a <gateway relate> command. To zap the current (main) database specify DEFAULT as the database logical name. You cannot zap a database if it is open by another user, or if you have it open twice. If you are having trouble, make sure you only open it once using a relate command. See also EXCLUSIVE or IF EXCLUSIVE. <GATEWAY ZSEARCH ZQUERY > optional parameters: ZSERVERID= ZSERVER= CLASSIFICATION= SUBJECTSOURCE= ZQUERY is the search to be done. It must be one or more of the following: TITLE=searchTitle AUTHOR=searchAuthor ISBN=ibnNumber ISSN=issnNumber SUBJECT=subject Either ZSERVERID or ZSERVER must be supplied.
Page 88 of 93
Alternatively, it may be a PQF search which uses the Z39.50 way of specifying a search. In such a case the ZQUERY must consist only of: PQF=pqfExpression
ZSERVERID is the ID of the Z-Server to use; the details of this are located in the ZTARGET database. Alternatively you can use ZSERVER and the Z-Server with a matching name in the ZTARGET DB will be used. You must provide either ZSERVER or ZSERVERID. CLASSIFICATION can have one of 3 values; ABRIDGED, UNABRIDGED and ALL (anything else is interpreted as ALL). Some 082 tags may be removed before the marc record is imported, this parameter controls which 082 tags will be preserved in each marc record. If ABRIDGED is selected; only abridged 082 tags will be preserved for each record, unless there are none in which case only the last 082 tag is preserved. Similarly for UNABRIDGED. If ALL is selected, all 082 tags are preserved. SUBJECTSOURCE can have any string value. Some SUBJECT tags may be removed before the marc record is imported, this parameter controls which SUBJECT tags will be preserved in each marc record. The definition of a SUBJECT tag is anything in the MARCDEFN DB with a CONCNAME of SUBJECT. If a (non empty) string is passed through in this parameter, only subjects with a $2 subtag that matches this parameter will be preserved. This is unless there are no SUBJECT tags with a matching $2 tag, in which case all SUBJECT tags are preserved.
Page 89 of 93
SESSION Database
The session database is actually a Concordance database used to monitor and control access with the Gateway program. A new session record is created each time you start a session. Following is a table of the fields defined for use within this database. Some fields are optional; these are marked as such. TIMESTAMP Required: Holds your session timestamp value. The timestamp value is made up of: JJJHHMMSShh JJJ - is the Julian date HH - is the hours MM - is the minutes SS - is the seconds hh - is the hundredths of seconds Required: This is the last time you were active. This value is used to identify sessions that have expired. (See the ExpiryMinutes in the Registry or Gateway.INI file). Optional: Will hold the validated username, if there is one. Optional: Will hold the validated password, if there is one. Optional: The contents of a SECURITY field in the clients record will be copied here for ease of access in checking the security options at a later date. Required: Records the last used direction when reading records from the database. Required: Holds the local filename assigned to the SnapShot file. Optional: Holds the current application directory (if there is one). This allows different forms to be stored in different directories, but the form need only be referenced by name. Required: Contains the name of the lock field used in the record update. Optional: Reserved for future use. Required: Records failure messages from the authentication process Optional: This field receives a copy of the current parameters whenever a SAVEFORM variable appears in the parameter list. The saved data is used in the Gateway Retrieve command to restore the values of the previous search form. Required: Holds details of the searches performed and the results. Optional: Holds statistical data on the number of bytes received and sent to the user.
LASTTIME
USERNAME PASSWORD SECURITY
DIRECTION SNAPSHOT APPLICATION
LOCKFIELD LOCKVALUE FAILURES CURR_SEARCH
STRATEGY BROWSE
Page 90 of 93
ALIAS
Optional: If your login names are different to your alias values. Once the username is verified the program will automatically populate this field with the ALIAS. Use the <gateway parameter name=alias> to retrieve and use this value. Populated with the date the record was created. Populated with the number of minutes between the TIMESTAMP and the LASTTIME. This will effectively provide the best estimate the system can provide on the duration of a session. Populated with the number of searches performed Populated with the number of times the Gateway has been run for this session.
DATEENTERED ELAPSED
SEARCHCOUNT PAGECOUNT
Page 91 of 93
Common Errors
404 Not Found The URL address is not correct. Check the directory path used to locate Gateway.exe. Remember the URL root is not always the same as the drive root directory. The web server was unable to execute the Gateway program, or the program failed. If you are able to run the Gateway satisfactorily from the server console but not other workstations then the error is a permissions problem. Check that the Gateway.exe can locate and load the Conwin.dll required to access the Concordance databases (if it is in the same directory as the Gateway program this is usually ok). If desperate here we can turn on the debugging option to find out where the program is stopping. The Web server is unable to access or execute the program. Check that the intranet user (or the authenticated user) has read and execute access to the Gateway.exe and forms directory. Also check that the Web Server has the directory flagged as executable. Unable to locate or open the named Concordance database. This may be due to a number of circumstances: a) the Gateway.ini file could not be located, b) the database could not be located, or c) the database could not be accessed due to security or some other limitation. Gateway was unable to open the named Concordance database. This may be due to a security limitation, or the database may be corrupt (e.g. required files may be missing). The timestamp being used is no longer valid. Either the timestamp is not current or has expired. Allocate a new timestamp by calling the Gateway with no timestamp parameter.
500 Server Error
Cannot open
Couldn't find....
Failed to open.
error: access not allowed
error: failed to open form={formname} This message is issued by GWID.EXE and says that the program was unable to open the form name specified in the http request. Check that the form name is correct, check also that the form is accessible by the authenticated user. Ensure the relative directory name is valid, if you are unsure copy the form to c:\temp\formname and then use form=c:\temp\formname as the parameter.
Page 92 of 93
Gateway Reference Guide error: failed to restore snapshot The previous execution of the Gateway program was unable to save a snapshot of the database. Check that the Gateway is able to write to the temporary directory (have the temporary files been created). Also check whether the records in the Session database are being appended.
error: remote user is not secured for this operation This message is issued by GWID.EXE and is indicative that the program is unable to identify the users sign-on. It could be the user is actually anonymous, or the remote_user environment variable is not being passed correctly by the web server. {a line of garbage} The Web server has located the Gateway program but instead of executing the program it has simple returned it as HTML text. Move the Gateway program to an executable directory or flag the current Gateway directory as executable. The program appears to work but no form is displayed. This is most likely due to the form file not being accessible. Check the Settings registry key or section within the Gateway.INI file for the FormFolder= setting. It should point to a directory where all of the forms are located. Normally the setting will be "FormFolder=forms" indicating the forms are in a sub-directory below the gateway program. Also check the name of the form is correctly typed. Also check security access to the forms. The Gateway program has a very slow response, maybe around 30-60 seconds to return the simplest of forms. This is mostly likely due to the programs inability to locate the Session database, probably because of an invalid UNC or network resource. If the simplest forms are ok but the search and display forms experience the delay then a similar error maybe experienced attempting to access the databases.
{blank response}
{slow response}
Page 93 of 93

Oliver-Liberty Gateway Reference Manual

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Oliver-Liberty Gateway Reference Manual

Uploaded by

Copyright:

Available Formats

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Installation Security settings

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

ON Domain\IUSR_GATEWAY (type and confirm password)

Full access Change None Change

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Registry Configuration

Gateway Reference Guide

Gateway Reference Guide

The Gateway INI File

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

<GATEWAY APPEND RULES=ruleName> <GATEWAU APPEND RULES=STORE:storename>

<GATEWAY APPEND DATABASE=logical FIELDMATCH=prefix UNIQUE=fieldname DATEFORMAT=format SEPARATOR=sep>

Gateway Reference Guide

Gateway Reference Guide

<GATEWAY ARCHIVE DATABASE=logical> additional parameters: UNIQUE=fieldname OVERWRITE=fieldname,fieldname, RELATED=logical

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

<GATEWAY COPYFILE FROM=filename TO=filename> additional parameters: SLASH=FORWARD | BACK

<GATEWAY COPYGROUPING TRANSLATE=translateform DISPLAYRESBOXITEM>

Gateway Reference Guide

<GATEWAY CYCFIELDS FIELDS=fieldname/separator,fieldname/separa tor... SUBFIELD=separator> additional parameters: HIGHLIGHT=OFF COUNT=number

<table> <tr><td>Collection</td> <td>Location</td> <td>Status</td></tr> <GATEWAY CYCFIELDS

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

Gateway Reference Guide

additional codes: START=value

<GATEWAY DATE> <GATEWAY DATE FORMAT=fmt ADJUST=num> additional parameters: VALUE=yyyymmdd

Gateway Reference Guide

<GATEWAY DELETE> Additional parameters: DATABASE=logical UNIQUE=fieldname, FILE=filename

Gateway Reference Guide

additional parameters: DATABASE=logical ADJUST=n MAX=m

Gateway Reference Guide

additional parameters: DATABASE=logical

<GATEWAY DUPCHECK FIELDS=storename TAGNAME=text>

<GATEWAY ELSE> <GATEWAY EMAIL ADDRESS=emailAddress CC=ccAddressList SUBJECT=parameter CONTENT=parameter>

Optional parameters: SENDER=emailAddress

HTMLEMAIL=true ATTACHNAME=name ATTACHCONTENTS=storeName ATTACHFILES=fileNameList

Gateway Reference Guide

Gateway Reference Guide