Welcome to the SDK

  • Welcome to the SYSPRO Software Development Kit

  • SYSPRO 6.1 SP1

  • e.net solutions

  • What's new

  • Additional help for developers

Published November 2012

SYSPRO Ltd

http://www.syspro.com

Developers

developers@za.syspro.com

Copyright

Copyright © 1994-2012 SYSPRO Ltd. All rights reserved


About the SDK

SDK

About the Software Development Kit

Welcome to the Software Development Kit

Welcome to the latest edition of the SYSPRO and e.net solutions Software Development Kit (SDK) documentation.

This version of the Software Development Kit documentation is focused on SYSPRO 6.1 SP1. It is intended to provide Net Express developers, and other interested parties, insight into the major upgrade in technology, features and functionality included with this significant release.

Net Express 5.1

For the first time SYSPRO has been developed using Net Express 5.1 and therefore, even if you are an experienced Net Express developer, you should immediately read the topic about Setting up a Net Express 5.1 development environment.

What else should I read?

If you are an experienced SYSPRO developer you should also read the What's new topic that summarizes the main changes to the development environment. This summary contains links to the all the SYSPRO 6.1 development features. What's new topics marked [image] have been added or updated since SYSPRO 6.1 was first released.

If you are new to SYSPRO development then you should seriously consider using e.net solutions. This allows C# developers and other COM based development environments to interact with SYSPRO 6.1.

What about developing for previous versions of SYSPRO?

Some obsolete information that related specifically to SYSPRO 6.0 or prior releases has been removed from this version of the SDK documentation. See the Support Zone for the archived version of this documentation.

Run-time Requirements

This edition of the documentation provides information you need to develop code for the following target versions:

  • SYSPRO 6.1 e.net solutions

  • SYSPRO 6.1

Developer information relating to SYSPRO 6.0, Encore 5.1 and prior versions is available on the Support Zone in a separate (legacy) software development kit documentation help file.

What is the SYSPRO e.net Solutions SDK?

SYSPRO e.net solutions provides a COM interface to SYSPRO 6.1 functionality. The e.net SDK is aimed at developers wishing to access the rich SYSPRO functionality from third party systems using COM and .NET technology - this includes the development of Internet Applications.

In addition the e.net Document Flow Manager allows you to automate the flow of documents into and out of SYSPRO - this can be used together with Microsoft BizTalk Server or can run standalone.

An introduction to e.net and a description of the e.net object model, XML Schemas and Business objects are included together with some Sample code. e.net can be used by developers using C#, VB.NET, ASP.NET, VB and ASP 3.0.

What is the SYSPRO SDK?

The SYSPRO SDK is aimed at developers who wish to write new programs and systems or to customize existing programs to run from SYSPRO. It is primarily aimed at developers using Net Express and the Dialog System.

The SYSPRO SDK includes sample source code, copybooks, file handlers, and compiler support files.

After reading this introduction it is recommended that you read Setting up a development environment.

Where Should I Start?

There's something for everyone depending on your knowledge and experience. Some good places to start are:

  • If you are new to e.net solutions or want to see how to access SYSPRO functionality from C#, VB.NET, ASP.NET, VB and ASP 3.0 then start with the introduction to e.net and the topic on Invoking e.net Methods.

  • If you want to automate the handling of documents coming into your company from your suppliers or customers then see the Document Flow Manager Overview.

  • If you have not worked with XML then now is the time to start. Read the XML Overview topic for the basics of XML and provides links to other XML related information.

  • The What's new section is continually being updated - so even if you are an experienced SYSPRO developer check out this topic on a regular basis.

  • Setting up a development environment takes you through installing the SYSPRO SDK. If you are developing SYSPRO programs then you should do this first to install the sample source code and compiler support files.

  • Basic sample program is a walk through of a sample SYSPRO application and how it is constructed. Useful if you haven't worked on SYSPRO 6.1 or SYSPRO 6.0 before.

  • Functions by name and Functions by type are the SYSPRO source code function references. These are a complete explanations of the functions available in PROBEGIN.PRO. A knowledge of these is important for new and existing developers working with SYSPRO.

  • Dialog functions by name and Dialog functions by type are the screenset function reference. This explains all the functions available from a screenset using the standard SYSPRO copybooks.

  • File status codes is a reference of the most common Net Express run-time codes returned by the file handling functions. It also summarizes the most likely reason for many of these error codes.

  • SQL Server tuning and Transaction Processing topics cover how developers can get the best from SYSPRO running on SQL Server.

  • The Source code samples provide demonstrations of various programming techniques for SYSPRO developers.

  • If you are having deployment problems for your SYSPRO custom programs, perhaps only on certain platforms, then see the Deploying Custom Programs topic.

  • There are a number of articles on various topics including SYSPRO Diagnostics, Developing for 1024 x 768 Resolution environment and Creating and deploying your own Help documents

Where Can I Find Additional Developers Information?

No matter how thorough the Software Development Kit documentation there will always be questions asked by developers.

By registering for the SYSPRO Support Zone you have access to the Developers Forums. This can be used to post developers questions and to interact with other SYSPRO developers.

If you have not yet registered for the SYSPRO Support Zone then Click here to learn more and/or to register.

The Developers section on the Support Zone also has recent information, other articles and the latest version of this SDK documentation.

Also...

Remember your local regional distributor has many years of experience developing custom software around e.net solutions, SYSPRO 6.1 and SYSPRO 6.0 and can assist with the most common issues.

If you find any incorrect or incomplete information in this SDK Documentation or would like to know more then please let us know using developers@za.syspro.com. Please note that this email address is only to be used for SDK Documentation.

Copyright Notice

Copyright © 1994-2011 SYSPRO Ltd. All rights reserved.


What's New

SDK

What's New

What's New in SYSPRO 6.1 SP1

The following new features have been implemented and documented in SYSPRO 6.1 SP1. These are the main topics that have been added/changed since SYSPRO 6.0 issue 010 SP2. In addition corrections have been made for problems reported with previous versions of the documentation.

The items marked [image] have been added or updated since SYSPRO 6.1 was first released.

Technology / Function

Description

What's new about SYSPRO 6.1 SP1

This topic covers the main features of SYSPRO 6.1 SP1 from a developers perspective together with details about database changes for 6.1 SP1.

SYSPRO 6.1 SP1 is a minor update to SYSPRO 6.1 and has minor changes to the database.

What's new about SYSPRO 6.1

This topic covers the main features of SYSPRO 6.1 from a developers perspective together with details about database changes for 6.1.

Since SYSPRO 6.1 was first released a new version of Net Express 5.1 WrapPack 4 has been released and this has prompted some additional information about fetching SQL nvarchar strings.

Setting up a 6.1 Environment

This is a new topic aimed specifically at setting up a development environment for SYSPRO 6.1.

This includes information about setting up Net Express 5.1.

The 'Compile Single File' information example has been revised since the SDK was first released for SYSPRO 6.1.

Business Object Reference Library

From SYSPRO 6.0 Issue 010 the list of Business objects and the sample XML in, out and schemas are no longer being maintained in this help file.

You should use the Support Zone at www.syspro.com to access the Business Object Reference Library.

Data Dictionary Conventions

This topic has been revised to explain how you can define a GUID in your record layouts.

In addition the explanation about how you define a time field has been clarified.

Data Dictionary Export

This topic has been revised since SYSPRO 6.1 was first released to include the new function 'Create columns script'.

It also explains the new 'Table and column filter' used when generating Table and Column definitions.

Data Dictionary Validation

There is a new Data Dictionary Validation utility provided with SYSPRO 6.1. This is designed to make it much easier for developers to verify their new record layouts, or changes to existing ones, conform to the conventions and best practices used by SYSPRO development.

Debugging on Unix

This topic has been revised as we now use Server Express 5.1 for Unix server deployment.

Default role during e.net logon

This topic has been revised to document the new <DefaultRole> XmlIn element that can be passed to the e.net Logon method.

Developing for 1024 x 768 Resolution

This topic has been revised. In addition it also documents a new parameter that can be used to suppress the 800x600 warning when SYSPRO is first loaded. This is useful when SYSPRO is used on a hand held device.

Importing and Exporting Text Files

If you develop code to import or export text files and wish to process special characters, such as TAB, LF or CR, then read this article that explains how to disable NULL insertion.

IMPMSG.IMP

The file IMPACT.ERR has been renamed to IMPMSG.IMP from SYSPRO 6.1.

PROFIND.PRO

This copybook containing wildcard matching logic has been revised to provide example code and describes a newer and simpler method of matching patterns.

Also consider using the SQL-GENERATE-WHERE-LIKE function when matching data in SQL Server environments.

Resource Locking

This article explains the new resource locking functions and introduces the test harness used to demonstrate the locking functions.

Sample program SDK009

This is a new sample program that demonstrates how to use LIST.PRO/WRK to call IMPLST or IMPLSC.

IMPLST allows you to pass two lists (available and assigned items) and move one list to another.

IMPLSC allows you to view a list of items and check/uncheck one or more of them using a simple user-interface.

Sample program SDK010

This is a new sample program that demonstrates how to generate XML and pass this directly to an SRS report. The report will be printed/previewed as normal.

Sample program SDKCB6

This is a new sample program that demonstrates opening an XML file and parsing it using the SYSPRO XML parser.

See the topic calling business objects overview for more information about this and other sample code.

Shared Inventory Files

This topic describes how the shared inventory id works and to which modules and files it applies. Including the new Warehouse Management (WMS) and Quality Management (QMS) files.

SQL Server Tuning Code

This topic covers how to determine the version of SQL Server being used.

It also has been extensively revised as the limits have been significantly raised from previous versions. For example you can now retrieve from more tables, more columns and more characters per column than SYSPRO 6.0.

See What's new about SYSPRO 6.1 for a list of the new capabilities.

SQL 2 character aliases

The SQL Server Tuning Code topic has been enhanced to allow you to specify two character aliases which now allows you to access up to 42 tables in a single SELECT statement.

See the sub-topic Defining 2 character table aliases in the generic tuning code topic.

Testing File Status Codes

This topic summarizes the typical file status conditions that should be tested after each type of file access.

ADD-CHG-DEL-NOT-FOUND

ASK-BRW-MAINT-CONFIRM-MBOX

ASK-BRW-MAINT-RET-MBOX

These functions provide standardized messages when developing browse and maintenance programs.

CALC-DATETIME-AGE

CALC-DATETIME-NEW-DATE

CALC-DATETIME-NEW-DATE-NUM

These functions provide date ageing and date calculations working with date-time fields. i.e. where you have both date and time values.

These functions have been included in SYSPRO 6.1 and were also available from SYSPRO 6.0 Issue 010 SP2 Port 35.

CALL-BO-POST-RTGL

This function is to be used by Net Express developers when invoking a business object that requires to post to the Real-Time GL (RTGL).

It is an extension of the CALL-BO-POST function.

CHECK-MAINTENANCE-OTHER-PROG

This function can be used to check whether another program can be run based on the current security settings.

CLEAR-FORCE-CHANGE-PASSWORD

This function allows you to programmatically clear the 'force password change' flag against an operator.

CREATE-DIRECTORY-ON-CLIENT

CREATE-DIRECTORY-ON-SERVER

These two new functions allow you to create folders on the client and server respectively.

EDIT-DATE-TO-USER-FORMAT-CYMD

This function can be used to edit an 8 digit date into a short date, long date or report date format.

GENERATE-VALID-FILE-NAME

This function is useful where you want to generate a file name based on a key or entered field and you need to be sure that only valid characters are used.

GET-COMPANY-LIST-ALL

GET-COMPANY-LIST-ALL-COMMA

GET-COMPANY-LIST-INV

GET-COMPANY-LIST-INV-COMMA

These functions allow you to retrieve a list of all companies on the system and all companies that have the same shared inventory id as the current company.

INVOKE-MESSAGE-BOX

INVOKE-MESSAGE-BOX-RESET

The existing function to invoke a message box has been enhanced to allow you to clear any 'Do not show this message again' check box.

INVOKE-TASK-DIALOG

This is a new function used to invoke a task dialog user interface element - a more sophisticated type of message box.

IS-LEAP-YEAR

This function is used to determine if the year provided is a leap year and how many days there are in February for the selected year.

OBJECT-COUNT-START

OBJECT-COUNT-END

These functions can be useful to help verify that your program does not have any memory leaks.

OUTPUT-SYSTEM-JOB-LOG

This function is used to write entries to the System Audit log file new to SYSPRO 6.1.

PRINT-OPEN

This topic has been expanded to include an explanation about how to check for a different program's default settings when opening the printer.

SQL-GENERATE-WHERE-LIKE

This function is useful when building optimized SQL commands and you wish to search using wildcards.

REFRESH-SECURITY-SETTINGS

This function allows you to refresh the current security and other settings for the current operator, role and company.

RESOURCE-LOCK-ADD

RESOURCE-LOCK-ADD-MSG

RESOURCE-LOCK-DELETE

RESOURCE-LOCK-TEST

RESOURCE-LOCK-TEST-MSG

These Resource Locking functions can be used to lock various types of resources other than traditional table and row locks.

For example when editing alternate stock codes you may want to prevent others from editing alternate stock codes for the same 'parent' part at the same time.

S-OSMKDR

S-OSMKDRS

These two new screenset functions allow you to create folders on the client and server respectively.

SET-FORCE-CHANGE-PASSWORD

This function allows you to programmatically set the 'force password change' flag against an operator. This forces an operator to change their password the next time they login.

TRANSLATE-TEXT

This function is part of the Language Translation capabilities of SYSPRO. This function can be used to lookup a single foreign or customized phrase.

TRANSLATE-TEXT-ADD

TRANSLATE-TEXT-GET

TRANSLATE-TEXT-INIT

TRANSLATE-TEXT-LIST

These functions are part of the Language Translation capabilities of SYSPRO. This set of functions are used to translate multiple phrases.

VERIFY-ACCESS-ACCOUNT

VERIFY-ACCESS-CONTACT

FILTER-ACCESS-ACCOUNT

FILTER-ACCESS-ACCOUNT-MAINT

FILTER-ACCESS-CONTACT

FILTER-ACCESS-CONTACT-MAINT

These Contact Management Security functions have been documented for the first time.

See also

e.net overview


SDK

What's New

Additional help for developers

No matter how thorough the Software Development Kit documentation there will always be questions asked by developers.

Developers Forum

SYSPRO has several active developer forums on our SYSPRO Support Zone.

By registering for the SYSPRO Support Zone you have access to all the Developers Forums. This can be used to post developers questions and to interact with other SYSPRO developers.

If you have not yet registered for the SYSPRO Support Zone then Click here to learn more and/or to register.

The Developers section on the Support Zone also has recent information, other articles and the latest version of this SDK documentation.

Remember your local regional distributor has many years of experience developing custom software around e.net solutions and SYSPRO 6.1 (and earlier versions such as SYSPRO 6.0) and can assist with the most common issues.

If you find any incorrect or incomplete information in this SDK Documentation or would like to know more then please let us know using developers@za.syspro.com. Please note that this email address is only to be used for SDK Documentation.

See also

e.net overview, SYSPRO Overview


Setting up a Develpment Environment for SYSPRO 6.1

SYSPRO SDK

Overview

Setting up a SYSPRO Development Environment for SYSPRO 6.1

This Software Development Kit is targeted at developers wishing to customize or develop new programs and systems around SYSPRO. It is aimed at developers using Micro Focus Net Express and the Dialog system to create their customized programs.

Getting your development system set up appropriately is an important step in the development process.

This topic is specifically aimed at setting up a development environment for SYSPRO 6.1.

This document recommends that you setup your system in a similar way to that used at SYSPRO. Whilst the choice is yours - this is the tried-and-tested way of setting up a development system and various utilities and batch files may assume this structure. The remainder of this document and the SYSPRO SDK generally assumes that you have configured your system as recommended.

Note that if you are only interested in SYSPRO e.net solutions then you do not need to follow these steps.

This document will guide you through the process of setting up your development environment.

  • Installing SYSPRO

  • Installing MS SQL Server 2005 or later

  • Installing Net Express 5.1

  • Installing the SYSPRO SDK

  • Setting up a new BASE directory

  • Setting up the custom program and screenset location

  • Adding your program to CUSTOM.IMP

  • Setting up TOOLKIT.INI

  • Setting up the COBCPY and COBIDY variables

  • Setting up a command prompt for batch compiling

  • Setting up the Net Express IDE

  • Compiling a program from the Net Express IDE

  • Compiling a program from the command prompt

  • Animating a program

  • Setting up the Dialog System

  • Setting up standard bitmaps for use within the Dialog System

  • Setting up a system for Unix deployment

Installing SYSPRO

You must have SYSPRO 6.1 installed.

Install the system in a standalone environment (not client/server). You can use the programs that you develop on mapped and client/server system but it is recommended that you setup your development system for a standalone environment so that you can easily Animate (debug) your programs.

It is assumed that you have installed SYSPRO using the following directory structure (although any folders can be used).

\Program Files\Syspro | Root directory
\Program Files\Syspro\Base | Base directory (main executables, libraries, image samples, etc.)
\Program Files\Syspro\Base\Bin | User control programs (listviews, toolbars etc.)
\Program Files\Syspro\Base\Ui | User control XML support files (listviews and toolbars)
\Program Files\Syspro\Base\Dd | Data dictionary files
\Program Files\Syspro\Work | Working directory (IMPACT.INI and company control files)
\Program Files\Syspro\Programs | Standard program directory
\Program Files\Syspro\Screens | Standard screenset directory
\Program Files\Syspro\Data | Data directory

After installing SYSPRO 6.1 ensure that you can log into SYSPRO and run standard programs as expected.

Note: It is strongly recommended that you always use the latest software development kit as new facilities and features together with bug fixes will have been applied. In addition new sample source code will be made available. If you are having a problem please verify that you are using the latest copybooks before contacting SYSPRO.

Installing MS SQL Server 2005 or later

If you wish to test your programs running on SQL Server then you should install it at this time and ensure that SYSPRO is running correctly accessing the SQL Server database. It is recommended that you install Microsoft SQL Server 2005 or later. However SQL Server 2000 will work when the correct service packs have been applied - not recommended.

It is recommended that you select a Custom install and select a Binary collation such as Latin1_General_BIN (or another case sensitive collation). SYSPRO requires a case-sensitive collation. Binary will give the best performance.

When selecting a case-insensitive collation the collation name contains the letters CI

If you wish, it is possible to use SYSPRO on an instance of SQL Server using a case insensitive collation - however in this case you should manually create the SYSPRO database and ensure that it has a case sensitive collation.

Note the copyright and licensing limitations on using this product.

Installing Net Express 5.1

SYSPRO 6.1 development requires Net Express 5.1.

The following guide is designed to assist you in installing Net Express 5.1. Over time Micro Focus may change the exact wording and dialog boxes so the following is designed to highlight the most important points.

During the install use the Custom Setup to ensure that you have the following minimum list of components selected for installation. You can select more components if that is applicable to your development environment.

Once the installation has completed you can run Net Express 5.1.

Remember to setup the appropriate variables and compiler options (described below).

Note: It is recommended that you immediately download the latest FixPacks from Micro Focus.

Installing the SYSPRO SDK

The SYSPRO SDK is provided as a ZIP file called SDK*.ZIP. Ensure you are downloading and installing the appropriate version for SYSPRO 6.1 - use the very latest if multiple versions are available.

The latest versions of these SDK ZIP files are available on the Developers section of the Support Zone.

To install it you should perform the following at a command prompt: (this assumes the name SDK61.ZIP)

  1. Change to your root directory e.g. CD \

  2. Copy SDK61.ZIP to \

  3. Use Windows to extract the contents of this folder

Note that prior versions made use of the PKUNZIP command however this does not support long file names and therefore is no longer used. This will then extract approximately 55MB of files in various sub-directories.

Each folder in this structure is designed to hold various file types. The directories and their contents are summarised below:

Directory | Contains | Notes
\rnd60 |  | Base for SYSPRO development
\rnd60\source | *.CBL | Source code
 | COMP*.* | Command line compiler support files
 | *.TEM | Data dictionary template files
 | LENGTH.* | Length utility for calculating record lengths
\rnd60\source\copy60 | *.MA? | Record layout copybooks
 | *.SEL | SELECT statement copybooks
 | *.CFL | File logic copybooks
 | *.WRK, *.PRO | Standard function copybooks
 | *.LNK | Inter-program linkages
 | *.CPY | Standard and modified Micro Focus copybooks
\rnd60\source\copy60\new |  | Temporary directory for data dictionary
\rnd60\source\binsrc | *.CBL | User-control programs
 | *.CPY | Toolbar copybooks (legacy)
 | COMP*.* | Command line compiler support files
 | *.IMP | Data block import files
\rnd60\source\fh | FH*.CBL | SQL File handler source files
 | COMP*.* | Command line compiler support files
\rnd60\prg | *.INT, *.GNT | Compiled programs
 | *.IMP | Standard import files
\rnd60\gui | *.GS | Screensets - editable
 | *.RS | Screensets - read only
 | *.CPB | Data block copybooks
\rnd60\base | IMPACT.EXE | Main SYSPRO executable
 | *.EXE | Other executables
 | *.DLL | Libraries
 | *.GNT, *.INT | Support programs
 | *.BMP | Sample bitmaps
 | *.CUR | Sample mouse pointers
 | IMPWRK.INI | Pointer to work directory
 | TOOLKIT.INI | SYSPRO SDK INI file
\rnd60\base\bin | *.INT, *.GNT | User-control programs and Win32 programs
\rnd60\base\fh | *.GNT | SQL File handlers
\rnd60\base\dd | *.DAT, *.IDX | Data dictionary data files & Report Library
\rnd60\base\ui | *.XML, *.XCB | User interface XML and XCB files
\rnd60\base\htmlhelp | *.htm | SYSPRO Help files in HTML format
\rnd60\base\samples | *.HTM, *.JPG, *.XML | Sample HTML and other documents
\rnd60\base\settings | *.PRF | Operator preferences
 | *.XML, *.DAT, *.IDX | User interface persistent files
 | *.TXT, *.SQL | Various files for logging and other usage
\rnd60\work | IMPACT.INI | Configuration file

Setting up a new BASE directory

  1. To simplify the development process it is recommended that you setup a new base directory rather than using the standard \Program Files\Syspro\Base installed as standard.

  2. After you installed the SYSPRO SDK you have a directory called \rnd60\base.

  3. Copy the contents of \Program Files\Syspro\Base and all its sub-directories to \rnd60\base

  4. If you have used the recommended directory structures you can run a batch file called SDKBASE.BAT from \rnd60\source.

  5. Change your shortcut that you have used to run SYSPRO so that the Target and Start in directories are \rnd60\base.

  6. Test this shortcut to make sure it works ok before continuing.

Setting up the custom program and screenset location

  1. Load SYSPRO and select Setup > System Setup from the main menu.

  2. Select the Other Paths tab and change the Custom directories values as follows:

Program directory: | \rnd60\prg
Screenset directory: | \rnd60\gui

  3. Save and exit SYSPRO.

Adding your program to CUSTOM.IMP

When SYSPRO runs a program it looks in the standard program and screenset directories. In addition if you have added your customized program to the text file CUSTOM.IMP then your program will be loaded from the customized program and screenset directories.

For example to add a program called CUSP10 to CUSTOM.IMP

  1. Edit CUSTOM.IMP in your working directory (\Program Files\Syspro\Work\CUSTOM.IMP).

  2. If there is already a CUSTOM.IMP then add the following lines. If it does not exist then create one as shown below.

    CUSTOM.IMP     is an ASCII file that lists the customized programs on your system. You can specify whether these programs are for everyone system-wide, for specific companies, groups or only for certain operators.

    ; CUSTOM.IMP
    ; Code   Prog   Program ;Comment (must be prefixed by ;)
    ; ------ ------ ------  ----------------------------------------------
    A        CUSP10         ;This custom program is available to everybody

    Ensure you have aligned the columns exactly as shown above (8 spaces between the initial A and the program name). See Deploying custom programs for more information.

    The CUSTOM.IMP file is read when you log into SYSPRO - so if you make changes you must log out for these to take effect.

    You must have the Screen Customization Kit Module licensed against your company for this to work.

Setting up TOOLKIT.INI

Once the SYSPRO SDK has been installed you should review the contents of your TOOLKIT.INI file. This file resides in your base directory (e.g. \rnd60\base).

The file TOOLKIT.INI defines the location of various development directories and files. For SYSPRO 6.1 there are two entries. They default to:

SRCNEW=\RND60\SOURCE

SRCCPB=\RND60\SOURCE\COPY60

If required simply change the line beginning SRCNEW= to point to the location of your source files (templates etc) and change SRCCPB= to point to the location of your copybook folder (*.MAC etc). You must not prefix the folder name with a drive letter - the drive defaults to the same drive as the location of the SYSPRO base folder.

The Data Dictionary Validation and Import and Data Dictionary Export functions will use the locations specified in this file.

If you find that Data Dictionary Validation and Import is not working correctly then you should verify the value of the SRCCPB= entry.

Setting up a COBCPY and COBIDY environment variables

It is recommended that you setup both COBCPY and COBIDY environment variables to point to your copybook and program folders respectively.

This is typically performed using the Windows control panel. Set the variables with the following values:

SET COBCPY=c:\rnd60\source;c:\rnd60\source\copy60;c:\rnd60\gui

SET COBIDY=c:\rnd60\prg

Note that if you wish to animate user-controls (such as listviews) then you will need to set your COBIDY variable to the following values:

SET COBIDY=c:\rnd60\prg;c:\rnd60\base\bin

Also, if you wish to animate the SQL file handlers then you will need to set your COBIDY variable to the following values:

SET COBIDY=c:\rnd60\prg;c:\rnd60\base\bin;c:\rnd60\base\fh

Setting up a command prompt for batch compiling

It is recommended that you use a command prompt for compiling programs. This provides the ability to compile a program and it's related components. It also edits the appropriate data block copybook when required.

When Net Express 5.1 is installed it adds a Command Prompt icon. This is a shortcut to a batch file called CREATENV.BAT. The location of this file varies depending on your version of Windows and the location selected at installation time. For example you may find the file at the following locations:

Version of Windows | Example Default Location
Windows XP + Vista | C:\Program Files\Micro Focus\Net Express 5.1\Base\BIN
Windows 7 | C:\Program Files (x86)\Micro Focus\Net Express 5.1\Base\Bin

Edit your CREATENV.BAT and add the lines highlighted in red. The example CREATENV.BAT files shown may not exactly match your file depending on the installation folders and exact Net Express version.

Example CREATENV.BAT for Net Express 5.1

@echo off

rem Create NetExpress Environment

"%cd%\cblpromp.exe" >> "%temp%\setenv.bat"

call "%temp%\setenv.bat"

del /q "%temp%\setenv.bat"

rem check for vista and server 2008 documents folder

if exist "%USERPROFILE%"\Documents set mydocs=%USERPROFILE%\Documents

if not exist "%USERPROFILE%"\Documents set mydocs=%USERPROFILE%\My Documents

if not exist "%mydocs%\Micro Focus\Net Express 5.1\WORKAREA" md "%mydocs%\Micro Focus\Net Express 5.1\WORKAREA"

type "%cd%\cobver"

cd /d "%mydocs%\Micro Focus\Net Express 5.1\WORKAREA"

set mydocs=

SET COBCPY=c:\rnd60\source;c:\rnd60\source\copy60;c:\rnd60\gui

SET COBIDY=c:\rnd60\prg;c:\rnd60\base\bin

SET NX=5.1

CD \RND60\SOURCE

You can also add your own SET commands after the SET COBIDY= line as required. Note that depending on the installed location of Net Express and the SYSPRO SDK you may need to change these lines as appropriate.

On recent versions of Windows you may be prevented from editing files in the program files folder as you may need administrator level access.

Create a NX variable to indicate the version of Net Express being used

To avoid accidentally using the wrong version of Net Express with the wrong version of SYSPRO source code we have implemented an environment variable since SYSPRO 6.0 Issue 009 called NX. This should have the value 5.1 when using Net Express 5.1 with the SYSPRO 6.1 Software Development Kit.

It is recommended that your Net Express command prompts are configured to set this variable appropriately. You will note that the line SET NX=5.1 was included in the CREATENV.BAT file shown above.

Note: The SYSPRO 6.1 batch file COMPILE.BAT will not proceed unless NX is set to 5.1

Setting up the Net Express IDE

Once Net Express 5.1 has been installed and you have edited the command prompt (CREATENV.BAT) you are ready to load Net Express and configure it as follows.

Setting the Options > Compile Single File string

Replace the default string with the following:

%FILENAME NOGNT WB3 WB CSI ANIM EDITOR(MF2) ENSUITE(3) INT(c:\rnd60\prg\%BASENAME.INT) DIR(c:\rnd60\source\companim.dir);

The COBIDY directive indicates where the .IDY file will be generated when compiling the program from the Net Express IDE.

The INT directive indicates where the .INT file will be generated when compiling the program from the Net Express IDE.

The DIR directive indicates that additional directives will be used from the file COMPANIM.DIR from the source folder.

Important - the additional directives specified in COMPANIM.DIR must be used else programs developed for SYSPRO 6.1 will not work as expected. The directives in COMPANIM.DIR have changed since SYSPRO 6.0.

Setting the Animate > Settings values

Update the animator settings with the following values:

Start Animating at:

c:\rnd60\base\impact.exe

Local working directory:

c:\rnd60\base

Command line parameters:

{set as required}

If you changed the default location of SYSPRO remember to change all the applicable entries above.

You can add various command line parameters to automate loading SYSPRO when animating. For example if you use operator code ADMIN and company A you can use:

/oper=ADMIN /comp=A

Compiling a program from the Net Express IDE

To Compile a program from Net Express

  1. Use File > Open and edit the required source file

  2. Compile the program using Project > Compile (Ctrl+F7)

If your program is using a screenset and you have edited the copybook then you should create a new version of the data block copybook (.CPB). However the default SYSPRO screensets will prefix each field with the screenset identifier.

The compiler usually reports that D-DATA-BLOCK is not found when this occurs. The simplest way to correct this is to compile the program from the command prompt (see below). In addition the command line compiler batch file will compile all associated user-control programs (such as listviews and toolbars).

Compiling a program from the command prompt

To Compile a program from the Net Express command line open a Net Express 5.1 command prompt and type the following:

  1. CD \rnd60\source

  2. COMPILE SDK008

Hint: Use COMPILE /H For help on options

The compile process will edit the copybook and replace the field prefix with the letter D. It also verifies that the standard data block fields are 100% correct. Note that all associated user-control programs such as listviews and toolbars will be automatically compiled.

Animating a program

  1. Either compile the program from within Net Express (Ctrl+F7) or, from a Net Express Command prompt type:

    CD \rnd60\source
    COMPILE /A SDK008

  2. Then from within Net Express

    Select Animate > Start Animating

  3. Select OK

  4. Run SYSPRO as normal and from the menu use File > Run and enter your program.

    Animator will take a few seconds to load and will then show your source code.

    If the program is not found then check you have added the program to CUSTOM.IMP correctly (see above) and that you have the Screen Customization Kit licensed against the company.

  5. If the program does not 'break' into animator then check that it was compiled to \rnd60\prg and that there is an IDY file in this folder. Also check that you have a COBIDY environment variable set so that the IDY file is correctly located.

Setting up the Dialog System

It is recommended that you change the Dialog System system-wide defaults as shown below.

These can be changed by loading the Dialog system and then selecting the Options > Configuration > Defaults menu choice, making the changes below, Save the settings and then immediately exit the Dialog system and reload it.

The recommendations are:

Setting | Value | Notes
AUTO RESTART | Yes | Helps general editing
DEFAULT GRID | 0004,0004 | Helps alignment
AUTO PROPERTIES | No | Asks properties dialog
DATA PROMPTED MODE | No | Can enable by double clicking
DIALOG PROMPTED MODE | No | Simplifies dialog editing
DIALOG TABLE EVENT PROMPTING | Yes | Adds appropriate defaults
MOUSE BUTTON CONFIGURATION | DS21 | Easy to resize objects
AUTO RESIZE CHARACTER | X | Average width for sizing
PROMPT WHEN DATABLOCK > 64K | Yes | Helps avoid mistakes
DATA BLOCK FLAGS EIGHTY EIGHTS | No | Required for SYSPRO
DATA BLOCK ANSI CONSTANTS | No | Required for SYSPRO
DATA BLOCK MF-CONSTANTS | No | Required for SYSPRO
DATA BLOCK INDEXED BY CLAUSE | No | Required for SYSPRO
INDEXED BY GROUP NAMES | No | Required for SYSPRO
PREFIX FIELDS BY SCREENSET ID | Yes | Required for SYSPRO

Setting up standard bitmaps for use within the Dialog System

SYSPRO screensets use a set of standard bitmaps that need to be copied to the Dialog System bin directory. To make the necessary changes perform the following:

  1. Exit from the Dialog System - else the files may be locked or in-use

  2. Change to \rnd60\base

  3. Run DSUPD. This has the following lines:

copy IMP50.DLL "C:\Program Files\Micro Focus\Net Express 5.1\DialogSystem\BIN"

copy DS.ICN "C:\Program Files\Micro Focus\Net Express 5.1\DialogSystem\BIN"

Note that you may need to copy these files manually if the Dialog System location is different to that shown.

The next time that you load the Dialog System you should have access to the standard SYSPRO bitmapped buttons - such as the browse button.

On recent versions of Windows you may be prevented from editing files in the program files folder as you may need administrator level access.

Setting up a system for Unix Deployment

From SYSPRO 6.1 we use Server Express 5.1 on Unix/Linux servers. This is very compatible with Net Express 5.1 - even to the extent that the compiled object code (*.INT) is compatible.

Therefore for SYSPRO 6.1 we recommend that you develop your applications using Net Express 5.1 and use a binary transfer utility (such as ftp) and copy the compiled INT code. Remember that Unix/Linux is case sensitive so you should ensure that the case of the programs is correct. If in doubt check the case of the regular SYSPRO programs on the server platform.

See the topic Debugging on Unix for more information about Unix specific development and debugging issues.

See also

Source code samples, Screen Customization Kit, Deploying Custom Programs, Developing for 800 x 600 Resolution, Data Dictionary Import, Record Layout


Copyright Notice

Copyright Notice

Copyright © 1994-2012 SYSPRO Ltd. All rights reserved.

SYSPRO is a trademark of SYSPRO Ltd. All other trademarks, service marks, products or services are trademarks or registered trademarks of their respective holders.

SYSPRO Ltd reserves the right to alter the contents of this document without prior notice. While every effort is made to ensure that the contents of this document are correct, no liability whatsoever will be accepted for any errors or omissions.

See also

Welcome, What's New


e.net overview

e.net SDK

Overview

SYSPRO e.net solutions Overview

SYSPRO e.net solutions is the latest technology product from SYSPRO that provides a COM interface to the existing business logic in SYSPRO.

In addition e.net solutions also consists of a set of .NET technology Web-based Applications using the COM interface and the Document Flow Manager helps you automatically manage incoming documents from your customers or suppliers.

Why have SYSPRO developed e.net?

Traditionally developers working with SYSPRO 6.1 (or earlier versions such as SYSPRO 6.0 or Encore 5.x) generally needed to work with Net Express and the Dialog System to develop their application. You would have to use our standard copybooks for the record layouts (tables and columns) and you would use our standard routines to handle file access etc.

Whilst this give tremendous power to a developer it can be daunting for new developers to learn this technology. In addition it's relatively difficult to integrate disparate products to/from SYSPRO 6.1.

e.net is SYSPRO's way forward to counter the growing need of customers to integrate, collaborate or develop around the existing SYSPRO product. e.net delivers a tactical and technology sound development strategy that allows developers and customers to extend SYSPRO's functionality.

What does this mean to me as a developer?

Basically e.net provides a COM interface that allows C#, VB.NET, ASP.NET, VB and ASP 3.0 developers to access SYSPRO functionality via an object model. In fact any COM enabled language or application can use the e.net object model.

During installation e.net will register the classes and methods from this object model. From there it's relatively simple to use the various methods.

See the simple example below - this logs into SYSPRO using the Utilities.Logon e.net method and obtains and displays a profile string.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Syspro As New Encore.Utilities()

Try

UserId = Syspro.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Fetch Logon profile Information

Dim LoginProfile As String

Try

LoginProfile = Syspro.GetLogonProfile(UserId)

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

Response.Write("The login profile is: " & LoginProfile)

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Syspro.Logoff(UserId)

Syspro = Nothing

To see a similar example in other languages see the Sample Code topic.

What else does e.net provide?

In addition to providing a COM interface to SYSPRO, e.net contains Web-based Applications for many of the existing SYSPRO functions. These are developed using Microsoft's .NET architecture.

For example all the previous Web Applets have been replaced with a Web interface using the .NET architecture. This of course uses the COM interface to SYSPRO.

e.net solutions also contains a Document Flow Manager that allows automation of business flows. This allows documents received from your customers or suppliers to be automatically processed by an e.net business object including optional XML transformations.

This e.net SDK documentation provides information to assist developers in accessing the rich functionality of SYSPRO using the Object model reference library, Sample Code, XML Schemas and much more.

If you are new to e.net then read the invoking e.net methods topic and then look at the Object model to see the classes and methods available. The Sample Code can help get you started.

Copyright Notice

Copyright © 1994-2010 SYSPRO Ltd. All rights reserved.

See also

Object model, XML Schemas, Business objects, invoking e.net methods, e.net Resource Handling


Invoking e.net Methods

This topic covers how to invoke the various method calls available in SYSPRO e.net solutions.

e.net consists of a number of classes, and within each class a number of methods. The table below shows these classes and methods. Note that the majority of these method calls require an XML string as an input parameter and return an XML string as an output parameter.

Class

Description and methods

Utilities

This class contains miscellaneous facilities available from e.net solutions.

There is a Logon method that is required to start an e.net session. This is used to authenticate a connection and return a valid UserId. The UserId is required for all subsequent e.net methods.

There is a Logoff method that is used to gracefully close the e.net session.

There is a GetLogonProfile method used to retrieve parameters about the current e.net session.

There is a Run method to be used to run a Net Express custom program.

Query

Query Business Objects do not update or change the underlying database. They simply retrieve data, often applying business rules to the returned information.

The Query Business Objects need to be passed an XML string containing the parameters identifying what information is to be returned. They then retrieve this information and return the result as an XML string.

There is a Query method that can invoke many 'Query' business objects.

There is a Fetch method that returns information about a single row in any table in the database.

There is a Browse method that can 'browse' on tables in the database. This returns a series of rows as an XML string. The number of rows returned and other parameters can be configured to end-user requirements.

There are NextKey and PreviousKey methods that allow you to navigate up and down the rows in a table.

Transaction

The Transaction class includes methods for posting transactions.

The Post method is used to actually post information to a 'Transaction' business object. These business objects take 2 XML strings - the document to be posted and a parameter list.

The Build method is used to prepare an XML document for use with the Post method. This can make it easier for a developer to actually use the Post method.

Setup

The Setup class is used to add, update and delete rows from a SYSPRO database. Appropriate business rules will be applied - for example you cannot delete a stock code if there is a sales order for it.

There is an Add method to add rows to a SYSPRO table.

There is an Update method to change data in an existing row.

There is a Delete method to delete data from a SYSPRO table.

Apart from the utilities class the other classes and their method work in a similar manner, as explained below. The method calls for the Utilities class are documented separately.

For examples about how to call various methods see the individual method topic and also the Sample Code section.

What should I do if I receive error 163 - Illegal Character in Numerc Field?

If you invoke an e.net business object and you receive an error 163 - Illegal character in numeric field - this means that you have not configured the appropriate switch to ignore this message.

You should have an environment variable COBSW=-F (the -F must be in CAPITALS).

Component interface for the Query class

Here follows an example of invoking the Query.Query method:

XmlOut = Query.Query(UserId, BusinessObject, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a SYSPRO Query business object. The format of this parameter is of type string.

XmlIn is a well formed XML string. The format of this parameter is type object.

XmlOut is the result returned as type string and is formatted as XML data. Click here for an example.

Method parameters are passed by value.

Component interface for the Transaction class

Here follows an example of invoking the Transaction.Post method:

XmlOut = Transaction.Post(UserId, BusinessObject, XmlParameters, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a SYSPRO Post business object. The format of this parameter is of type string.

XmlParameters is a well formed XML string containing parameters for the posting method. The format of this parameter is type object.

XmlIn is a well formed XML string containing the data to be posted. The format if this parameter is type object.

XmlOut is the result returned as type string and is formatted as XML data.

Method parameters are passed by value.

Note that the main difference between the Transaction class and the Query class is that there is an extra XmlParameters parameter.

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, Sample Code


e.net Diagnostics

Developers have great flexibility in the way that they can invoke e.net business objects. However it can be difficult for developers to debug their applications. In a real-world environment the sequence and frequency of the calls to e.net may be complex and is generally transparent to the end-user.

e.net solutions provides a diagnostic aid to assist developers identifying what business objects are being invoked, how frequently and in what sequence.

Note that the Document Flow Manager also calls e.net business objects but has it's own diagnostic trace. e.net business objects invoked from the Document Flow Manager will not output entries to this log file. See the topic Document Flow Manager Diagnostics.

In addition if you find that a business object appears to hang after being called once in an ASP 3.0 environment see the explanation of other diagnostic options (eg 'enet03') to assist in detecting the problem.

Configuring e.net Diagnostics

To configure e.net to produce a trace of the business objects being called use the SYSPRO System Setup program and select the enet01 choice against the 'Diagnostics:' prompt as shown below.

The Trace File

As soon as this 'enet01' setting has been saved, Encore.dll will start producing a trace file named Base\Settings\enetlog.txt

This file contains a trace of every call to e.net solutions showing the date, time, method, business object, status and operator.

Warning - this file may grow rapidly.

See the following example:

Availability

This trace is available from SYSPRO 6.0 issue 006 and later and requires Encore.dll (6.0.004) issued with this version of SYSPRO 6.0.

Intended use

Remember that enabling this trace will slow Encore.dll and is only intended to be used in a development environment or temporarily in a production environment.

This feature is subject to change in the future.

The topic SYSPRO Diagnostics details additional diagnostic options that can be used for e.net.

See also

e.net overview, UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, Sample Code, Document Flow Manager Diagnostics, SYSPRO Diagnostics


e.net Memory Handling

e.net SDK

Resource Handling

Resource Handling

This topic discusses resource issues related to 3rd party applications calling e.net solutions Business Objects.

Logging in and out of e.net solutions

It is highly recommended that you use the Utilities.Logoff method call to inform e.net solutions that you have finished with the session created for the current UserId.

Creating and destroying objects

It is good practise to destroy the objects created when you have finished with them. The exact syntax used to destroy objects differs from language to language.

See the following VB.NET example where the object 'Syspro' is destroyed using the statement Syspro = Nothing

' This code will Logon to SYSPRO and then Logoff

' Logon and trap any exceptions

Dim UserId As String

Dim Syspro As New Encore.Utilities()

Try

UserId = Syspro.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Logoff and Destroy any objects created

Dim ReturnCode As Long

ReturnCode = Syspro.Logoff(UserId)

Syspro = Nothing

Garbage Collection in the .NET Environment

Some documentation recommends that you let the .NET Framework automatically handle garbage collection. The system determines when resources are running low and will automatically remove unused objects and frees up unused memory.

However as the .NET framework must make assumptions about the available resources and performance of the system it can be more efficient if you call the garbage collection yourself - this will free any resources immediately.

Summary of garbage collection in managed code

If you are running a managed code application (an application written in .NET) the run time simply allows you to create as many objects as you need. You can run your application as many times as you want - you will notice that the memory usage increases. When the .NET runtime finally detects that your process is going to run out of resources it calls garbage collection which will clear out any objects that you did not finalize thus freeing up any memory that is not being used.

It is good practice to always destroy objects after you have used them whether they are managed code objects or COM objects.

See also

UserId, e.net Overview, Sample Code


Document Flow Manager Overview

The e.net Document Flow Manager (DFM) provides the facility to automatically process incoming and outgoing XML documents. This system helps SYSPRO companies to improve the partnerships with their suppliers and customers.

For example - typically companies send documents to suppliers via traditional post, fax, or email. Data capture clerks enter these documents on the suppliers computer system. This commonly leads to transcription errors and duplicates effort. The Document Flow Manager can automate this process doing away with transcription errors and avoiding duplication of effort.

How does the Document Flow Manager work?

The Document Flow Manager can be configured to receive incoming documents against various email accounts and/or documents placed in pre-defined folders. When these documents are detected they are read and placed in the Microsoft Message Queue (MSMQ).

The Document Flow Manager Main Service then retrieves messages from the MSMQ and, based on the DFM configuration from within SYSPRO, invokes the appropriate e.net solutions business object. The business object will process the document and respond with an acknowledgement. Acknowledgement information can be returned back to the originator.

All documents received and acknowledgements returned are in XML format. These can be optionally transformed using a user-defined XSL transformation.

A log of documents processed can be retained to provide document traceability.

Recommended Sequence when Setting up the Document Flow Manager

Step | Description
1 | Add a new operating system user
2 | Set permissions on the SYSPRO folder structure
3 | Give permissions for email accounts
4 | Give permissions on folders to poll (if known)
5 | Give permissions to any XSL and response folders
6 | Set local policy settings ‘Logon as service’
7 | Define the name of the Message Queue in the ‘Message Queue Setup’
8 | Add a SYSPRO operator for the service - recommend ‘__DFM’
9 | Install the required services
10 | Define the contracts from within SYSPRO

Further information about the Document Flow Manager

See the following topics for more information about the Document Flow Manager

  • The Document Flow Manager Details topic contains a more in-depth discussion of DFM capabilities

  • The Document Flow Manager System Requirements topic defines operating system and other pre-requisites

  • The Document Flow Manager Configuration topic shows how to configure the DFM from within SYSPRO before starting to install the DFM services

  • The Document Flow Manager Installation topic covers how to install and start the DFM services

  • The Document Flow Manager Diagnostics topic covers how to trace the e.net business objects being invoked from the DFM

  • Up-to-date information about installation, configuration and the latest features and are covered on-line in the Support Zone at www.syspro.com

  • Your local SYSPRO representative also can assist with DFM training. The Document Flow Manager Workbook covers all the topics explained here and contains practical exercises taking you through the setup, configuration and programming of the Document Flow Manager.

See also

e.net overview, e.net solutions business object, Microsoft Message Queue (MSMQ), XML Overview, Document Flow Manager Details, Document Flow Manager Installation, Document Flow Manager System Requirements, Document Flow Manager Configuration, Document Flow Manager Diagnostics


Document Flow Manager Details

e.net SDK

Document Flow Manager

Document Flow Manager Detail Explanation

The e.net Document Flow Manager (DFM) provides the facility to automatically process incoming and outgoing XML documents. This system helps SYSPRO companies to improve the partnerships with their suppliers and customers.

For example - typically companies send documents to suppliers via traditional post, fax, or email. Data capture clerks enter these documents on the suppliers computer system. This commonly leads to transcription errors and duplicates effort. The Document Flow Manager can automate this process doing away with transcription errors and avoiding duplication of effort.

Diagram showing the Key Components of the Document Flow Manager

How does the Document Flow Manager work?

The Document Flow Manager can be configured to receive incoming documents against various email accounts and/or documents placed in pre-defined folders. When these documents are detected they are read and placed in the Microsoft Message Queue (MSMQ). The DFM Configuration file defined from within SYSPRO allows you to configure what documents are to be handled and which folders and/or email accounts are to be polled. Any problems are logged to the standard Windows Event Log.

The Microsoft Message Queue ensures that the documents are then processed in a First In First Out sequence - even in the event of system failure, unexpected system shutdown or other serious system level problem.

The Document Flow Manager Main Service retrieves messages from the MSMQ and, based on the DFM configuration from within SYSPRO, invokes the appropriate e.net solutions business object. If required the XML document received can optionally be transformed using an XSL transformation before being passed to the business object. See the documentation in the Object Model Reference against the business object for details of the required XML inputs. The following methods document the most common business objects you will require:

Query.Query

Transaction.Post

Setup.Add

Setup.Update

Note that some business objects require XML parameters - these can also be defined using the DFM setup wizard.

The business object will process the document (reading and updating the SYSPRO database as appropriate) and respond with an acknowledgement in XML format. Note that if the business object raises an exception the Document Flow Manager will convert the exception message to an XML format message and return this string. Again you can select to optionally transform this response using an XSL transformation. The Acknowledgement information can be returned back to the originator by email and a SYSPRO operator can be informed of the action that was processed.

A log of documents processed can be retained to provide document traceability.

If required you can also place the XML response into a folder configured for Microsoft BizTalk Server. BizTalk can be setup to poll a folder and then process the document. You can use SMTP to send a message back to your supplier/customer with an embedded HTML document. You can even send an SMS if required.

See also

Document Flow Manager Overview, Document Flow Manager System Requirements, Document Flow Manager Configuration, Document Flow Manager Installation, Microsoft Message Queue (MSMQ), Microsoft BizTalk Server, e.net solutions business object, Document Flow Manager Diagnostics


Document Flow Manager System Requirements

To install and run the Document Flow Manger you need to have installed the following:

  • Windows 2000/XP

  • MSMQ – Microsoft Message Queue, installed via the add remove programs - Windows components. The MSMQ is used to queue the requests to the SYSPRO server.

  • SMTP – Simple Mail Transport Protocol, installed via the add remove programs – Windows components under IIS. The virtual SMTP server is used to send email – outgoing responses from the Document Flow Manager. If the SYSPRO application server cannot resolve the email address, the email could be forwarded to the companies email server. (SMART HOST).

  • SYSPRO version 6.0 or higher needs to be installed and the Document Flow Manager must reside on the SYSPRO Application Server as it uses the library routines made available by SYSPRO 6.0.

  • You need a valid license to run SYSPRO 6.0. The e.net System Manager and e.net Document Flow Manager must both be installed.

  • The Document Flow Manager makes uses of the following Microsoft COM components. These must be available for the DFM to function correctly.

COM Component | e.net component
CDO.Message | COMEML (SMTP)
Msxml2.FreeThreadedDOMDocument.4.0 | COMXML
Msxml2.FreeThreadedDOMDocument.3.0 | COMXML
MAPI.Session | IMPDFE (Email Poll)
MSMQ.MSMQQueueInfo | IMPDFM, COMMES
MSMQ.MSMQMessage | IMPDFM, COMMES

See also

Document Flow Manager Overview, Document Flow Manager Installation, Microsoft Message Queue


Document Flow Manager Configuration

Before installing and running the Document Flow Manager Services you must configure various settings from within SYSPRO. To do this you should load SYSPRO and from the menu select e.net solutions and then the Document Flow Manager Setup program.

Once the setup program has loaded select the Options menu option and then the Message Queue Setup option.

The Document Flow Manager Control Setup screen is then shown.

Message queue setup

Only the Private message queue is supported.

The Queue name can be left as SYSPRO and the Queue label as Document Flow Manager.

Email polling server setup (incoming documents)

In order to poll email accounts, the Document Flow Manager requires access to the Exchange Server. Enter the name of the Exchange Server to establish a valid login.

Email response server setup (outgoing acknowledgements)

The Document Flow Manager can return information or acknowledgement from incoming documents. This information is returned using the standard SMTP server (installed with IIS).

The SYSPRO application server would not normally have Exchange Server installed. The SMTP address effectively allows you to bounce the mail from one server to the next.

You can enter the IP address of the SYSPRO application server for the SMTP address and, within the configuration of the SMTP server, point to your Exchange server.

Defining SYSPRO Operators for use with the Document Flow Manager

The Document Flow Manager uses SYSPRO operator codes to perform functions and invoke the various business objects.

It is recommended that operator codes beginning with '__' (two underscores) are used. For example the operator code __DFM can be used for all Document Flow Manager processing.

Once you have added the __DFM operator code you should setup permissions so that this operator has access to all business objects that will be used by the Document Flow Manager.

Note that you cannot login to SYSPRO using an operator code beginning with two underscores. This means that any auditing (such as job logging) can be used to clearly see what has been done by the Document Flow Manager.

Defining a contract

Once you have saved these DFM settings you will need to configure each type of document (Query, Setup or Transaction) to be received. Each type of document that can be received is assigned a unique Contract number. A Wizard will take you through this process.

Once you have setup and saved the basic Document Flow Manager Configuration you are ready to install and setup the Document Flow Manager Services.

See also

Document Flow Manager System Requirements, Document Flow Manager Installation, Document Flow Manager Diagnostics


Document Flow Manager Installation

The Document Flow Manager comprises three services:

  • Document Flow Manager - Main Service (IMPDFM.EXE)

  • Document Flow Manager - Folder Polling Service (IMPDFF.EXE)

  • Document Flow Manager - Email Polling Service (IMPDFE.EXE)

Before you Install the Document Flow Manager Services

Important - Before attempting to install the Document Flow Manager Services ensure you have the minimum basic Document Flow Manager System Requirements and that you have setup the Document Flow Manager Configuration and added your __DFM operator code from within SYSPRO.

Prior to installing the Document Flow Manager Services, you need to address various permission issues.

Local security policy should be updated to allow the services to run as an operating system user. The services must have access to mailboxes on the exchange server or folders that must be polled either on the same server or a different server using a Universal Naming Convention (UNC).

The local security policy can be updated by accessing the Administrative Tools function (located in the control panel) and selecting the Local Security Settings icon. (Start > Settings > Control Panel > Administrative Tools > Local Security Settings > Local Policies >User Rights Assignment)

Double-click the 'Log on as a service entry' and add the user name required to run the Document Flow Manager.

If a new user name has been added to the server for the purpose of running the Document Flow Manager, ensure that the new user has permissions for the SYSPRO folder structure and any folders polled as well as any email accounts to be used.

Installing and Starting the Document Flow Manager Services

All the Document Flow Manager services are installed from the command line. The service will start immediately providing that all the parameters passed are valid. If the service fails to start (for example due to an invalid parameter) the cause is written to the NT event log.

Note that as part of the service installation process you must specify an operator code to be used. It is recommended to have previously setup a SYSPRO operator code called __DFM for this purpose.

All the values entered when installing the services are stored in the registry under their respective keys.

HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/Document Flow Manager

String | Description
Company | Valid licensed SYSPRO Company ID
Operator | Valid SYSPRO user (__DFM)
LangCode | Language code for error messages
Sleep | Time interval to poll in milliseconds

Other strings within this registry key are standard service keys.

On starting the service, a valid login is achieved followed by the initialization of the Microsoft Message Queue. The Microsoft Message Queue name is derived from that setup in the Document Flow Manager Setup program from within SYSPRO. This is covered in the Document Flow Manager Configuration topic. If this information has not yet been setup then the default name of SYSPRO is used and a private queue is generated. (Public queues are not supported at this time).

Once the Microsoft Message Queue objects have been created, the services begins a loop until the service is stopped. During the loop cycle, a message is extracted from the message queue. If there are no messages present, then the document processing is ignored.

On extraction, the message id is written to the NT application log. The DFM Main Service then calls the program COMDFP to process the message. Each message consists of two parts:

1. The message body

2. The message extension

COMDFP looks at the type of message being received, generates the message extension and calls the appropriate business object to handle the transaction.

Document Flow Manager Main Service - Command Line Parameters

The Document Flow Manager Main Service is installed from the command line and must be installed on the SYSPRO Application Server and run as a valid operating system user.

The Service has the following command line parameters:

Option | Description | Example
-I | Install | IMPDFM –i –o __DFM –c 1 –l 5 –u DOMAIN\Fred –p fredspassword
-o | Operator code (must be a valid operator code in SYSPRO)
-c | Company id (this has no reference to transactions posted)
-l | Language code for errors posted to the NT Event log
-u | A valid NT user name with relevant permissions
-p | NT user password
-r | Remove service | IMPDFM –r
-s | Start service | IMPDFM –s
-x | Stop service | IMPDFM –x
-v | Service status | IMPDFM –v

Note:

  • You must have at least one space between each parameter and the parameter value

  • The installation parameter values must not contain spaces - for example passwords with spaces are not accepted

  • The installation parameters can be submitted in any sequence

  • Under the local security policy settings, the NT user name supplied on the install command line must have permission to run as a service

Folder Polling Service - Command Line Parameters

The DFM Folder Polling Service is installed from the command line and must be installed on the SYSPRO Application Server and run as a valid operating system user.

The Service has the following command line parameters:

Option | Description | Example
-I | Install | IMPDFF –i –o __DFM –c 1 –l 5 –u DOMAIN\Fred –p fredspassword
-o | Operator code (must be a valid operator code in SYSPRO)
-c | valid Company id (this has no reference to transactions posted)
-l | Language code for errors posted to the NT Event log
-u | A valid NT user name with relevant permissions
-p | NT user password
-r | Remove service | IMPDFF –r
-s | Start service | IMPDFF –s
-x | Stop service | IMPDFF –x
-v | Service status | IMPDFF –v

Note:

  • You must have at least one space between each parameter and the parameter value

  • The installation parameter values must not contain spaces - for example passwords with spaces are not accepted

  • The installation parameters can be submitted in any sequence

  • Under the local security policy settings, the NT user name supplied on the install command line must have permission to run as a service

Email Polling Service - Command Line Parameters

The DFM Email Polling Service is installed from the command line and must be installed on the SYSPRO Application Server and run as a valid operating system user.

The Service has the following command line parameters:

Option | Description | Example
-I | Install | IMPDFE –i –o __DFM –c 1 –l 5 –u DOMAIN\Fred –p fredspassword
-o | Operator code (must be a valid operator code in SYSPRO)
-c | Company id (this has no reference to transactions posted)
-l | Language code for errors posted to the NT Event log
-u | A valid NT user name with relevant permissions
-p | NT user password
-r | Remove service | IMPDFE –r
-s | Start service | IMPDFE –s
-x | Stop service | IMPDFE –x
-v | Service status | IMPDFE –v

Note:

  • You must have at least one space between each parameter and the parameter value

  • The installation parameter values must not contain spaces - for example passwords with spaces are not accepted

  • The installation parameters can be submitted in any sequence

  • Under the local security policy settings, the NT user name supplied on the install command line must have permission to run as a service

See also

Document Flow Manager Overview, Document Flow Manager System Requirements, Document Flow Manager Configuration, Business object, Document Flow Manager Diagnostics


Document Flow Manager Diagnostics

Developers and support personnel have great flexibility in the way that they can configure the e.net Document Flow Manager. However it can be difficult to debug the Document Flow Manager configuration. In a real-world environment the sequence and frequency of the Document Flow Manager processes and the business objects it calls may be complex and is generally transparent to the end-user.

The Document Flow Manager provides a diagnostic aid to assist developers and support personnel identifying what business objects are being invoked, how frequently and in what sequence.

Configuring Document Flow Manager Diagnostics

To configure the Document Flow Manager to produce a trace of the business objects being called use the SYSPRO System Setup program and select the enet02 choice against the 'Diagnostics:' prompt. Once this 'enet02' setting has been saved, you should stop and restart the Document Flow Manager Service.

The Trace File

When the Document Flow Manager starts with the 'enet02' diagnostic option set it will start producing a trace file named Base\Settings\enetlog02.txt

This file contains a trace of every call that the Document Flow Manager makes to an e.net business object, showing the date, time, method, business object, status and operator.

Warning - this file may grow rapidly.

See the following example:

Availability

This trace is available from SYSPRO 6.0 issue 007 and later.

Intended use

Remember that enabling this trace will slow the Document Flow Manager and is only intended to be used in a development environment or temporarily in a production environment.

This feature is subject to change in the future.

See also

e.net overview, UserId, Error Handling, Document Flow Manager Overview, e.net Diagnostics, SYSPRO Diagnostics


Microsoft Message Queue (MSMQ)

The MSMQ is a First In First Out (FIFO) queue. This acts like a conveyor belt, as the folder and/or email polling services add messages to the queue they wait there until the Document Flow Manager Main Service takes them off of the queue and processes them.

The benefits of using the MSMQ are that if the Document Flow Manager Main Service or Operating system are stopped or fail in some way the documents are not lost – they remain in the queue until the Document Flow Manager Main Service takes them off of the queue and processes them.

Note that there is a 4MB limit to the size of each document in the MSMQ.

See also

Document Flow Manager Overview, Document Flow Manager System Requirements


Microsoft BizTalk Server

What does BizTalk do?

Microsoft BizTalk Server is a Microsoft application that allows suppliers and customers to send documents seamlessly via Internet email. It provides sophisticated functionality to configure and manage these relationships including conversion of data between customer/supplier information and your own system.

How does BizTalk integrate with applications such as SYSPRO?

BizTalk is configured to ‘listen’ for documents to arrive. When it finds a document, for example a purchase order, it passes the purchase order to the application, in this case SYSPRO, using an application adapter. The application adapter is a bit of code that is specific to SYSPRO and each type of document. This is typically a DLL that can only handle a single document type.

SYSPRO does not attempt to provide BizTalk application adapters as we would have to provide several hundred DLL's tightly coupled to the Biztalk server architecture. The problem is that if BizTalk were to change then each of these application adapters would have to be changed. Instead you can use BizTalk to listen for documents, convert or transform them using BizTalk and then pass them to the SYSPRO Document Flow Manager. In addition the DFM can be used to place responses in a folder that BizTalk can then use to respond back to the customer/supplier.

Many of SYSPRO’s customers do not require the sophistication of BizTalk and can simply use the Document Flow Manager without BizTalk.

If you are unsure whether you need the sophistication of BizTalk server and the Document Flow Manager or just require the Document Flow Manager (without BizTalk server) please discuss this with your local SYSPRO representative.

See also

Document Flow Manager Overview, Document Flow Manager Details


XML Overview

XML is rapidly becoming an industry standard way of passing information from one application to another. e.net methods take advantage of XML in that almost every parameter passed and returned uses XML.

An XML document consists of simple tags (called elements) that describe the data together with the actual data. XML can exist as a disk file (for example INVQRY.XML), as a string in memory or as a stream of characters sent across the internet.

Many e.net methods take XML input and return XML Output. XML is extremely flexible in that new elements can be added without breaking the interface. For example see the Query.Query method.

For information about the format of an XML document see the topic Well Formed XML. Note that some characters should be handled carefully.

However just by looking at an XML instance it may not be clear as to the valid elements and their values. This is where a Schema is used.

Schemas

A Schema is a definition file (with an XSD extension) that defines what makes up a valid XML document for the specific method call or object. It defines all the valid elements along with possible attributes and the values they can take. In addition there are comments to assist in understanding the element names and their uses.

For example the schema INVQRY.XSD defines the valid elements that can be passed to the Inventory Query business object.

The Schema Reference contains a detailed XSD Schema and XML instance for each business object.

See also

e.net overview, Object model, Query.Query, Well Formed XML, business object, XML Output


Well Formed XML

This topic provides guidelines for creating XML documents and some tips for overcoming problems using special characters such as <, > and &.

XML documents must be well-formed. That is, they must follow the rules for identifying document parts and creating nested element structures. These rules are explained below.

Document prolog

When XML documents are created they often include a document prolog. This is a standard header to indicate to an application or parser that this is actually XML.

For example

<?xml version="1.0" encoding="Windows-1252"?>

When e.net programs create XML documents (either as disk files or as strings/streams) they include the document prolog as shown above. Note that the version refers to the XML standards and not to SYSPRO or e.net software version. Also note that the encoding attribute Windows-1252 is the standard default used by e.net solutions.

It is highly recommended that any XML passed to e.net business objects also includes the above mentioned prolog.

Root element

An XML document can only have one document element (often known as the root element). The document element is a single element that contains all the content considered to be part of the document itself. The document root element is the first element to appear after the document prolog (the information at the top of the XML document).

All XML elements must have end tags

An element is a word or phrase enclosed in < and >. For example <Element>. Each element must have a matching end element (or sometimes called a tag). For example </Element>. While end tags/elements may be optional with HTML, all elements in XML must have an end tag/element.

For example

<Query>

<Key>ABC</Key>

</Query>

Spaces and Indentation

Spacing and indentation of XML elements are usually used purely for readability.

XML elements cannot overlap

If the start tag for an element appears within another element, it must end with the same containing element. For example the following HTML code suggests a combination of bold and italic by using overlapping tags.

<b>This is bold text. <i>This is bold italic text. </b>This is italic text.</i>

In a browser this would look as follows:

This is bold text. This is bold italic text. This is italic text.

In an XML parser, however all processing halts as soon as the </b> tag is encountered because the XML parser is looking for the </i> tag. To achieve the same formatting in XML, use the following syntax.

<b>This is bold text. </b><i><b>This is bold italic text. </b>This is italic text.</i>

Whilst this is slightly more work for XML document authors - it provides a leap forward for inter-operability. Because XML processors have far less 'guessing code' and they fit more easily into smaller-scale processing environments, like embedded systems. Structural ambiguities are eliminated from XML documents - all parsers see the same nested element structures.

All attributes must be quoted - whether they contain spaces or not

Attributes can be used to further describe an element.

For example:

<Warehouse FilterType="A" FilterValue="E,FG" />

You can use either single quotes or double quotes to surround the attribute value.

Using special characters <, > and & - CDATA sections

These special characters are used to define the structure of an XML document. Generally these cannot be used as element or attribute values else a parsing error will be returned.

There are standard character entities (special strings) that can be used to represent these characters as follows:

Character Entity

< &lt;

> &gt;

& &amp;

However this approach may cause a difficulty in a practical environment. For example suppose you have a stock code called Smith&Wesson and you wish to include this data within an XML document. When the XML document is parsed it will fail since the XML parser does not understand the & character.

To overcome this problem you could package the data as Smith&amp;Wesson, but that would require the developer to perform their own parsing on the data before building the XML string and passing it to the component.

Another technique is to use CDATA sections which preserve markup (special) characters. CDATA sections allow you to use sequences of characters within an XML stream that contain markup elements common to XML without violating XML well-formedness constraints.

CDATA sections use the string <![CDATA[ to indicate the start of a CDATA section and the string ]]> to terminate the section.

Here is a example of how a CDATA section is used to sort out the Smith&Wesson problem discussed earlier.

<Stockcode><![CDATA[Smith&Wesson]]></Stockcode>

CDATA sections provide a way to tell the parser that there is no markup in the characters contained by the CDATA section. This makes it much easier to create XML documents containing elements where markup characters might appear but where no markup is intended. For example when requesting data from an operator.

Case sensitivity

XML element names are case sensitive. The closing element must exactly match the case of the opening element. If you do not do this then the XML document will not be well-formed.

Note that e.net business objects ignore the case of incoming elements - so if the schema indicates that the root element of the Query.Query method requires <Query> it is equally valid to use <query> as long as the closing element has the same case.

See also

e.net overview, XML Overview, XML Output


XML Schemas

Many e.net methods take XML input and return XML output. XML is extremely flexible in that new elements can be added without breaking the interface. However just by looking at an XML instance it may not be clear as to the valid elements and their values.

A Schema is a definition file (with an XSD extension) that defines what makes up a valid XML document for the specific business object. It defines all the valid elements along with possible attributes and the values they can take.

However it is often much easier to see an example XML document. In many cases we have provided a sample XML instance. Remember than this is just an example and may not contain all the valid elements or valid values.

The Schema Reference contains a detailed XSD Schema and XML instance for each business object.

Note that the Schema Reference in this help file contains only a small sample of the available business objects. See the Business Object Reference Library on the Support Zone at www.syspro.com.

For information about the format of an XML document see the topic Well Formed XML.

See also

e.net overview, Object model, business object, XML Output


XML Output

All e.net business objects return XML strings. These strings are well formed and have a consistent prolog and root element.

To view an example XML output from the INVQRY business object click here.

The first part of the XML output contains information about the current environment. This can appear in one of two formats.

Environment information - Attributes

The default format contains attributes to the root element. See the following example:

<?xml version="1.0" encoding="Windows-1252" ?>

<InvQuery Language="05" Language2="EN"
 CssStyle="" DecFormat="1" DateFormat="01"
 Role="01" Version="6.0.010">

Note that the Root element (in this case <InvQuery>) indicates the business object being invoked.

In addition a number of attributes against the root element are returned that can be used by the developer to format the returned XML as required. These attributes are described below.

Environment information - Elements

Alternatively the environment information will be output as a set of elements beneath a <SystemInformation> node. You can see this by setting a <SystemInformationReqd> element to a value of 'Y' when using the Logon method.

See the following example:

<?xml version="1.0" encoding="Windows-1252" ?>

<InvQuery>

<SystemInformation>

<CssStyle />

<Language>EN</Language>

<DecFormat>1</DecFormat>

<DateFormat>01</DateFormat>

<Role>01</Role>

<Version>6.0.016</Version>

<CompanyId>1</CompanyId>

<CompanyName>SYSPRO Outdoors Company</CompanyName>

<OperatorCode>ADMIN</OperatorCode>

<OperatorName>SYSPRO Administrator</OperatorName>

<OperatorGroup>ADMIN</OperatorGroup>

<OperatorEmailAddress />

<OperatorLocation>Head Office</OperatorLocation>

<LocalCurrency>$</LocalCurrency>

<LocalCurrencyDesc>Dollars</LocalCurrencyDesc>

<GlPrdPerYear>12</GlPrdPerYear>

<ReportDate>May 29 2006 04:20 PM</ReportDate>

<UseSeparatorOnReports>Y</UseSeparatorOnReports>

<SeparatorToUse>,</SeparatorToUse>

</SystemInformation>

Language="05"

The Language attribute is a two character code identifying the language of the operator used by the Utilities.Logon method. This language code can be passed to the Logon method or the default will be used from the Operator code in SYSPRO. This is configured using the e.net Tab in the Operator Maintenance dialog box. Common language codes are:

05 - English

07 - French

12 - Spanish

15 - Chinese

Note that from SYSPRO 6.0 issue 010 onwards an additional Language2= attribute will be output that defines the new two character alphanumeric codes used to represent languages. It is recommended that the Language2= attribute is used in future applications rather than the Language= attribute.

Language2="EN"

The Language2 attribute is a two character code identifying the language of the operator used by the Utilities.Logon method.

This attribute is only available from SYSPRO 6.0 issue 010. Note that it is the alphanumeric equivalent of the language codes used prior to issue 010. Common language codes are:

EN - English

FR - French

ES - Spanish

ZH - Chinese

It is recommended that the Language2= attribute is used in future applications rather than the Language= attribute.

CssStyle=""

The CssStyle attribute returns the current 'Cascading stylesheets' setting defined against the Operator code in SYSPRO. This is configured using the Web-based Applications Tab in the Operator Maintenance dialog box. This attribute is used by the e.net Web-based Applications to determine the stylesheet (CSS) to be applied to the output.

If the 'Default style' is selected the CssStyle attribute is null, if a 'Company style' is selected then the CssStyle attribute contains the company id and if the 'Operator style' is selected then the 2 character 'Style suffix' is returned.

DecFormat="1"

The DecFormat attribute returns the current 'Decimal format' setting defined against the Operator code in SYSPRO. This is configured using the e.net Tab in the Operator Maintenance dialog box. Decimal formats returned include:

1 - #,##0.00

2 - # ##0,00

3 - {custom}

DateFormat="01"

The DateFormat attribute returns the current 'Date format' setting defined against the Operator code in SYSPRO. This is configured using the e.net Tab in the Operator Maintenance dialog box. Date formats returned include:

01 - CCYY-MM-DD

02 - DD/MM/YY

03 - MM/DD/YY

04 - YY/MM/DD

05 - DD/MM/CCYY

06 - MM/DD/CCYY

07 - CCYY/MM/DD

08 - {custom}

Role="01"

The Role attribute returns the current 'Functional Role' setting defined against the Operator code in SYSPRO. This is configured using the e.net Tab in the Operator Maintenance dialog box. Functional roles returned include:

01 - Employee

02 - Customer

03 - Supplier

Version="6.0.010"

The Version attribute returns the current version of the business object being invoked.

See also

e.net overview, Object model, Query.Query, Well Formed XML, business object, Sample XML Output


Sample Code

Sample Code

Throughout the SDK documentation for e.net solutions many code fragments have been included to help demonstrate use of the various methods. Each example uses one of the common object based languages.

This topic provides links to sample mini-applications in various languages.

Sample code to Logon and GetLogonProfile

These code samples show use of the Utilities.Logon method and then retrieve and display the Logon profile using the Utilities.GetLogonProfile method.

  • Sample Logon in VBS

  • Sample Logon in ASP.NET

  • Sample Logon in C#

Sample code to Logon and Post a Message to the Operator Inbox

These code samples Post a message to a SYSPRO operator's Inbox using the Transaction.Post method. The messages can be viewed from within SYSPRO.

  • Sample Post Message in VBS

  • Sample Post Message in ASP.NET

Notes on using VBS Scripts

The VBS scripts can be copied to the clipboard and pasted into NOTEPAD. They can then be saved as a file with a .VBS extension (for example Logon.VBS). You can then run the script by double clicking on it from within explorer. It is assumed that you have installed e.net solutions on your system for this to work successfully.

Remarks

Syspro continually develop and enhance their sample programs to demonstrate various programming techniques. Always use the latest software development kit to see the latest samples.

Please note that these programs are provided “as is” and have not been through the usual Syspro testing process nor are they intended to perform any specific business function. They are intended to demonstrate various programming techniques.

See also

Object Model, UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML


' This code will Logon and retrieve and display the Logon profile

call GetLogonProfile
Function GetLogonProfile

Dim OpPassword, Company, CompanyPassword, Message, LoginCode
Dim Xmlin, XmlParameters
OpPassword=""
XmlIn=""

' Ask the operator
operator = inputbox("Please enter the User name:","e.net solutions","ADMIN")

' Invoke the e.net solutions Utilities class
set Logon=CreateObject("encore.utilities")
on error resume next

' Login using operator code: ADMIN
UserId = Logon.Logon(Operator, OpPassword , Company, CompanyPassword, AUTO, ldNoDebug, encoreInstance_0, XmlIn)

' Trap any error from the login process
if err <> 0 then
   msgbox Err.Description,vbCritical,"e.net solutions"
   exit function
end if

' Note that there are no parameters required for this business object
XmlParameters = ""

' Invoke the GetLogonProfile method of the Utilities class,
XmlOut = Logon.GetLogonProfile(UserId)

' Display a message box with the returned result
msgbox xmlout, vbInformation, "e.net solutions"

set Logon = nothing
end function


' This code will Logon to SYSPRO and retrieve and display the Logon profile

' Logon and trap any exceptions
Dim UserId As String
Dim Syspro As New Encore.Utilities()
Try
    UserId = Syspro.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")
Catch exc As Exception
    Response.Write("Exception - message:" & exc.Message)
    Exit Sub
End Try

' Fetch Logon profile Information
Dim LoginProfile As String
Try
    LoginProfile = Syspro.GetLogonProfile(UserId)
Catch exc As Exception
    Response.Write("Exception - message:" & exc.Message)
    Exit Sub
End Try

' Display as an XML string
Response.Write(LoginProfile)
Response.ContentType = "text/xml"

' Logoff and Cancel your current Session
Dim ReturnCode As Long
ReturnCode = Syspro.Logoff(UserId)
Syspro = Nothing


' This code will Logon to SYSPRO and retrieve and display the Logon profile

UtilitiesClass Syspro = new UtilitiesClass();

string sUserId;
object oUserId;
string sLoginProfile;
object oLoginProfile;
object operator;
object operatorPassword;
object companyId;
object companyPassword;
Syspro.Language languageCode;
Syspro.LogDetail logDetail;
Syspro.Instance logInstance;

operator = "admin";
operatorPassword = "";
companyId = "";
companyPassword = "";
languageCode = Language.ENGLISH;
logDetail = 0;
logInstance = Syspro.Instance.EncoreInstance_0;

// Logon and trap any exceptions
try {
   oUserId; = Syspro.Logon(ref operator, ref operatorPassword, ref companyId, ref
companyPassword, ref languageCode, ref logDetail, ref logInstance);
   sUserId = (string) oUserId;;
    }
catch (Exception exc) {
   MessageBox.Show(exc.Message);
    }

// Fetch Logon profile information
try {
   oLoginProfile = Syspro.GetLogonProfile(ref sUserId);
   sLoginProfile = (string)oLoginProfile
    }
catch (Exception exc) {
   MessageBox.Show(exc.Message);
    }

// Logoff and Cancel your current Session
int ReturnCode;

ReturnCode = Syspro.Logoff(ref sUserId);


' This code will post a message to the Message Inbox in SYSPRO

call PostMessage
Function PostMessage

Dim Operator, OpPassword, CompanyID, CompanyPassword, Message, LoginCode
Dim XmlIn, XmlParameters
SourceLogon="ADMIN"
OpPassword =""

' Ask the operator and message text
operator = inputbox("Please enter the operator for whom the message is intended:","e.net solutions","ADMIN")

message = inputbox("Please enter the message text:","e.net solutions")

' Invoke the e.net solutions Utilities class
set Logon=CreateObject("encore.utilities")
on error resume next

' Login using operator code in SourceLogon
UserId = Logon.Logon(SourceLogon, OpPassword , CompanyID, CompanyPassword, AUTO, ldNoDebug, EncoreInstance_0, XmlIn)

' Trap any error from the login process
if err <> 0 then
   msgbox Err.Description,vbCritical,"e.net solutions"
   exit function
end if

' Invoke the e.net solutions Transaction class
set Transaction = CreateObject("Encore.Transaction")

' Note that there are no parameters required for this business object
XmlParameters = ""

' Build query string in XML
' Note that this shows a subset of the available XML elements for this business object
XmlIn = "<message>" &_
          "<item>" &_
            "<operator>" & operator & "</operator>" &_
            "<subject>" & message & "</subject>" &_
          "</item>" &_
        "</message>"

' Invoke the POST method of the transaction class using business object COMTIB (Post a message)
XmlOut = Transaction.Post(UserId, "COMTIB", XmlParameters ,XmlIn)

' Check return XML for errors by looking for any XML elements containing ErrorDescription
If InStr(xmlout, "ErrorDescription") > 0 Then
    Dim msgs
    msgs = "Error messages:" & VbCrLf
' Invoke the XML DOM
    set xmldoc = CreateObject("Msxml2.DOMDocument")
    set ErrorNode = new IXMLDOMNodeList
' Load the returned XML error list
    xmldoc.LoadXml(xmlout)
' Extract each error message
    For Each ErrorNode In xmldoc.documentelement.SelectNodes("//ErrorDescription")
        msgs = msgs & Errornode.text & VbCrLf
    Next
 ' Display list of errors and exit
    msgbox msgs,vbCritical,"Post Message Errors"
    xmldoc = Nothing
    exit function
end if

' Display XML returned
msgbox xmlout

set Logon = nothing
set Transaction = nothing
end function


' This code will post a message to the Message Inbox in SYSPRO

' Logon and trap any exceptions
Dim UserId As String
Dim Syspro As New Encore.Utilities()
Try
    UserId = Syspro.Logon("ADMIN", " ", " ", " ", 5, 0, 0, " ")
Catch exc As Exception
    Response.Write("Exception - message:" & exc.Message)
    Exit Sub
 End Try

' Run generic query returning a sales order
Dim SysproTrn As New Encore.Transaction()
Dim XmlOut As String

' Build an XmlParameter XML string to pass parameters
Dim XmlParameter As String
XmlParameter = "<?xml version=""1.0"" encoding=""Windows-1252""?>"

' Build an XmlIn XML string to pass data to be posted
Dim XmlIn As String
XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_
        "<message>" &_
           "<item>" &_
             "<companyid>A</companyid>" &_
             "<operator>ADMIN</operator>" &_
             "<date/>" &_
             "<time/>" &_
             "<messagetype>ENET</messagetype>" &_
             "<subject>Stock on hand low for item B100</subject>" &_
             "<fromoperator/>" &_
             "<fromname/>" &_
             "<programtorun>INVPEN</programtorun>" &_
             "<programparameters>B100</programparameters>" &_
             "<preventduplicate/>" &_
           "</item>" &_
        "</message>"

Try
    XmlOut = SysproTrn.Post(UserId, "COMTIB", XmlParameters, XmlIn)
Catch exc As Exception
    Response.Write("Unable to run business object COMTIB - Exception:" & exc.Message)
    Exit Sub
End Try
Response.Write(XmlOut)
Response.ContentType = "text/xml"

' Logoff and Cancel your current Session
Dim ReturnCode As Long
ReturnCode = Syspro.Logoff(UserId)
Syspro = Nothing


e.net Licensing Overview

This topic provides an overview of e.net solutions licensing.

Overview of available e.net solutions features

e.net solutions consists of three main features - they are:

e.net Business Objects

These are COM based components that allow 3rd party developers to access the rich functionality of the SYSPRO ERP solution. Typically each 3rd party application will use a number of e.net Business Objects. Business Objects are licensed at the Functional Area level. A Functional Area is simply a ‘group’ of Business Objects.

e.net Web-based Applications

These provide out-of-the-box Web-based solutions allowing internet and intranet access to the SYSPRO ERP solution. These applications use e.net Business Objects to access the SYSPRO ERP functionality. The e.net Business Objects used by the Web-based Applications are licensed separately from other e.net Business Objects.

e.net Document Flow Manager

This system allows documents entering your organization to be handled automatically. The system is typically configured to invoke e.net Business Objects to process the incoming documents. The Document Flow Manager requires a license based on the number of SYSPRO concurrent users (the individual e.net Business Objects used by the Document Flow Manager do not have to be licensed).

e.net licensing concepts

The basic philosophy of e.net solutions licensing is that you "Pay for what you use".

This means that each person (called a Named User) using e.net requires a license to access the Functional Areas that they use – no more, no less.

Functional Areas are logical groupings of Business Objects. For example an Inventory Query Functional Area contains several individual Business Objects performing ‘Inventory Query’ functions.

A simple example

If Named User ‘JOHN’ requires access to the Inventory Query Functional Area of e.net then ‘JOHN’ requires a single license for the Inventory Query Functional Area.

In addition, if Named User ‘MARY’ requires access to both the Inventory Query Functional Area and the Inventory Posting Functional Area, then she only requires a single license for each of these two Functional Areas.

In this example the Inventory Query Functional Area requires a total of 2 licenses (one for ‘JOHN’ and one for ‘MARY’) and the Inventory Posting Functional Area requires a single license (for ‘Mary’).

Summary of Named User licensing

To identify how many e.net licenses are required you need to determine how many people need to access each Functional Area.

Licensing using this method provides complete security control as each Named User is an Operator in SYSPRO. In addition you have complete traceability as the Operator code is used in audit trails and logging functions.

This simple ‘Named User’ licensing is available for both e.net Business Objects and e.net Web-based Applications.

Note: when configuring ‘Named User’ licensing for e.net Web-based Applications you need to determine which Functional Areas will be accessed via the Web-based Applications. These are the only e.net licenses required. For example suppose you wish ‘JOHN’ to access the Inventory Query Functional Area from the Web-based Applications then that is the only license required (the Web-based Application license for the Inventory Query Functional Area provides all the access you require for ‘JOHN’ to access the Inventory Query).

For more information developers should see the topic about Named User Licensing.

Additional Licensing Concepts

In addition to the simple Named User “pay for what you use” concept described above there are other methods of configuring e.net licenses. These can provide greater flexibility however there are also limitations in their application.

Guest/anonymous user licensing

(applies to both e.net Business Objects and e.net Web-based Applications)

In some environments you may require anonymous access to your application. Anonymous access generally provides Query functions allowing information to be viewed but not changed. The most common is when using the internet from a .com site – often when no prior-registration is required.

In this case, access to the underlying SYSPRO ERP data can be provided using a single Operator code configured as a 'Guest/anonymous user'. When configuring an Operator code as a 'Guest/anonymous user' you can define the number of concurrent users that may use this Operator code.

As mentioned previously this Operator code would typically have very limited access to the SYSPRO ERP application.

Use of the ‘Guest/anonymous user’ Operator code

When logging into e.net using an Operator code configured as a 'Guest/anonymous user' the system will ensure that the number of concurrent uses of this Operator code does not exceed the configured maximum.

Note: when using a 'Guest/anonymous user' Operator code, an automatic timeout of 30 minutes is applied. See the following example for how this is applied.

Example using a Guest/anonymous user

Assume your application provides anonymous access to a price lookup for various stock codes. You may want all of your 1000 customers to have access to this application (they will be 'Guest/anonymous users'). Remember they all get the same SYSPRO security permissions and you cannot distinguish from SYSPRO audits or logging who did what.

Rather than licensing the Inventory Query Functional Area (which provides the price lookup function) for all 1000 customers you can decide that only about 200 of them would typically use your applications within a 30 minute period.

In this case you could add an Operator code called 'PRICE' and configure it as a 'Guest/anonymous user' with 200 concurrent users. It is important to ensure that all security settings are configured to only allow access to the Inventory Query Business object providing the price look-up.

You then apportion 200 of your Inventory Query Functional Area licenses to the 'PRICE' Operator code.

Your application can then be used to provide Inventory price look-ups for up to a 200 concurrent users using the 'PRICE' operator code.

Note that if over 200 users attempt to use the 'PRICE' Operator code in a 30 minute period then they will be denied access.

For more information developers should see the topic about Guest/anonymous User Licensing.

Class of users licensing

(applies only to e.net Web-based Applications)

The e.net Web-based Applications provide for a Class of users to be licensed.

A Class of users is a 'group' for licensing purposes.

Example of using a Class of users

Assume you have 300 employees that need access to the e.net Web-based Applications. However at any one time only about 200 of these will be logged in - actively using the system.

In this case rather than requiring a license for all 300 Named Users you can create a Class called 'WEB' configured for 200 concurrent users. Each of the 300 Operator codes can be configured for Web-based Applications to belong to the ‘WEB’ Class.

When logging into the Web-based Applications the system will allow any 200 Operators belonging to the 'WEB' Class to be logged in and using the system concurrently.

Advantages of Class licensing

- When you know that use of the Web-based Applications is limited to a smaller number of concurrent accesses than the total number of people who 'ever' use the application this is a more efficient use of your licenses.

- You can configure a number of concurrent users for the Class

- You can configure a timeout period for the Class

Limitations of Class licensing

- Class licensing is only available for the e.net Web-based Applications

- An Operator code can only belong to a single Class for licensing purposes

For more information developers should see the topic about Class User Licensing.

See also

e.net overview, Named User Licensing, Guest/anonymous User Licensing, Class User Licensing


Named User Licensing

Named User licensing means that each Named User (defined as an operator code in SYSPRO) requires a license to access the Functional Areas that they use – no more, no less.

Functional Areas are logical groupings of Business Objects. For example an Inventory Query Functional Area contains several individual Business Objects performing ‘Inventory Query’ functions.

A simple example

If Named User ‘JOHN’ requires access to the Inventory Query Functional Area of e.net then ‘JOHN’ requires a single license for the Inventory Query Functional Area.

In addition, if Named User ‘MARY’ requires access to both the Inventory Query Functional Area and the Inventory Posting Functional Area, then she only requires a single license for each of these two Functional Areas.

In this example the Inventory Query Functional Area requires a total of 2 licenses (one for ‘JOHN’ and one for ‘MARY’) and the Inventory Posting Functional Area requires a single license (for ‘Mary’).

Use of the UserId with Named User Licensing

You pass an operator code to the Utilities.Logon method. This returns a UserId which identifies the session.

When you subsequently invoke an e.net method you must pass the same UserId to ensure that the same session is being referenced.

When using Named User licensing the UserId identifies the single session allowed by that operator code. If you use the Utilities.Logoff method the session is closed and the UserId cannot be used. This then free's up the Named User license for that operator code and another Utilities.Logon method can be used to start a new session for the same operator code.

Important

If a Utilities.Logon method is invoked for an operator code when a previous session is still being used for the same operator code the previous session will be terminated.

If this occurs the original session will return an exception when it next attempts to issue an e.net method using the original UserId.

Alternate styles when using Named User sessions

There are typically two styles of handling e.net sessions using Named User Licensing.

Short session style

The short session style means that whenever an e.net method is to be invoked you use Utilities.Logon to retrieve a UserId, then immediately invoke the required method and then use Utilities.Logoff. This keeps the session open for the minimum length of time possible.

This must be repeated for each e.net method to be invoked.

This style does have an overhead of a Logon/Logoff for each method to be invoked however in most real applications this has a negligible performance hit.

Long session style

The long session style means that you use Utilities.Logon to retrieve a UserId and then use this UserId to invoke multiple e.net methods. This may take place over an extended period of time without any ill-effects. When the session is to be closed you use Utilities.Logoff.

When using the long session method it is important that no other Logon is performed using the same operator code. If this occurs the original session will return an exception when it next attempts to issue an e.net method using the original UserId.

See also

e.net overview, e.net Licensing Overview, Utilities.Logon, Utilities.Logoff


Guest/anonymous User Licensing

When logging into e.net using an Operator code configured as a 'Guest/anonymous user' the system will ensure that the number of concurrent uses of this Operator code does not exceed the configured maximum.

Note: when using a 'Guest/anonymous user' Operator code, an automatic timeout of 30 minutes is applied. See the following example for how this is applied.

Example using a Guest/anonymous user

Assume your application provides anonymous access to a price lookup for various stock codes. You may want all of your 1000 customers to have access to this application (they will be 'Guest/anonymous users'). Remember they all get the same SYSPRO security permissions and you cannot distinguish from SYSPRO audits or logging who did what.

Rather than licensing the Inventory Query Functional Area (which provides the price lookup function) for all 1000 customers you can decide that only about 200 of them would typically use your applications within a 30 minute period.

In this case you could add an Operator code called ‘PRICE’ and configure it as a 'Guest/anonymous user' with 200 concurrent users. It is important to ensure that all security settings are configured to only allow access to the Inventory Query Business object providing the price look-up.

You then apportion 200 of your Inventory Query Functional Area licenses to the ‘PRICE’ Operator code.

Your application can then be used to provide Inventory price look-ups for up to a 200 concurrent users using the 'PRICE' operator code.

Note that if over 200 users attempt to use the ‘PRICE’ Operator code in a 30 minute period then they will be denied access.

How the 30 minute timeout is applied

Each 'Guest/anonymous user' operator code is configured with a number of concurrent users.

When Utilities.Logon is used to generate a new UserId this consumes one of the concurrent users for that operator code. This session stays active indefinitely (even after a Utilities.Logoff).

However, when using Utilities.Logon, if the maximum number of concurrent users for the 'Guest/anonymous user' is exceeded the e.net licensing system will determine when each session (UserId) was last accessed and find the session with the oldest of these 'last access' timestamps. If this session has not been accessed for 30 minutes then it will be terminated (invalidating the UserId) and the new session will be successful.

However if all sessions (UserId's) have been accessed within the past 30 minutes then they are deemed to be active and the new Utilities.Logon will return an exception.

Note about the 'last access' timestamp

Each session (identified by a unique UserId) records the date and time of the last e.net method that has been invoked. This 'last access time' is used when determining the 30 minute timeout.

Using the Guest/anonymous user licensing

Due to the 30 minute timeout used by the Guest/anonymous user licensing it is recommended that applications using this type of operator code use a 'long session style'.

This means that you use Utilities.Logon to generate a UserId and then invoke multiple e.net methods. These e.net methods can be invoked over a period of time. When you have finished with the operator code you should use Utilities.Logoff - however remember that this session is still active for 30 minutes.

If this limitation makes the Guest/anonymous user licensing impractical then it is recommended that you revert to use Named User licensing.

See also

e.net overview, e.net Licensing Overview, Utilities.Logon, Utilities.Logoff


Class User Licensing

Note - Class User Licensing applies only to e.net Web-based Applications

The e.net Web-based Applications provide for a Class of users to be licensed.

A Class of users is a 'group' for licensing purposes.

Example of using a Class of users

Assume you have 300 employees that need access to the e.net Web-based Applications. However at any one time only about 200 of these will be logged in - actively using the system.

In this case rather than requiring a license for all 300 Named Users you can create a Class called 'WEB' configured for 200 concurrent users. Each of the 300 Operator codes can be configured for Web-based Applications to belong to the ‘WEB’ Class.

When logging into the Web-based Applications the system will allow any 200 Operators belonging to the 'WEB' Class to be logged in and using the system concurrently.

How the Class of user licensing is handled

When you log into the e.net Web-based applications using an operator code configured as Class user then the Class code is located to determine the number of concurrent users and the user-defined timeout.

The number of concurrent users determine how many operator codes can be logged in concurrently belonging to the same class.

If you attempt to log into the e.net Web-based applications using an operator code configured as Class user but the number of concurrent users has been exceeded then the system will determine the last recently used object for each person belonging to the Class.

If the oldest session was used within the timeout period then all sessions are deemed to be active and the attempted Logon will fail. However if the oldest used session is older that the timeout period then it will be terminated (the UserId will be invalidated) and the new session will Logon successfully.

Note that when this old session is terminated this will return an exception message the next time that person attempts to use the e.net Web-based applications.

Customizing the Web-based applications

If you customize the Web-based applications and are using the session (UserId) generated by the Web-based application Logon then this session will be treated as if it is a standard e.net Web-based session.

The Class user licensing can be used, so can the Named User and Guest/anonymous licensing methods.

See also

e.net overview, e.net Licensing Overview, Utilities.Logon, Utilities.Logoff


Object model

e.net SDK

Object Model Reference

Object Model Reference

The following classes and methods are supported by e.net solutions. Note that many of these method calls provide generic access to many business objects.

Utilities Class

The Utilities class is used to Login to e.net and provide various other generic functions.

  • Utilities.Logon

  • Utilities.Logoff

  • Utilities.GetLogonProfile

  • Utilities.Run

Query Class

The Query class is used to query data in a generic way.

  • Query.Browse

  • Query.Fetch

  • Query.Query

  • Query.NextKey

  • Query.PreviousKey

Transaction Class

The Transaction class is used to post transactions.

  • Transaction.Build

  • Transaction.Post

Setup Class

The Setup class is used to add, change or delete information from the SYSPRO data structures.

  • Setup.Add

  • Setup.Update

  • Setup.Delete

See also

UserId, Error Handling, XML Schemas, XML Overview, Sample Code, XML Output


UserId

The UserId is a string that uniquely identifies an e.net solutions session.

The Utilities.Logon method is used to login to SYSPRO and generate a UserId string. This UserId must be used in all subsequent e.net calls to ensure that the same session is referenced. The Utilities.GetLogonProfile method can be used to return information about the current profile.

Use the Utilities.Logoff method to complete the session.

Hint - if you are having type mismatch problems with the UserId try defining it as a string as shown below

Dim UserId as String

See also

Utilities.Logon, Utilities.Logoff, Utilities.GetLogonProfile


Error Handling

e.net components automatically raise exceptions when critical errors are encountered.

An exception occurs where the component cannot complete it's task. For example the Inventory Query component requires a valid stock code - if the stock code is not valid then the component cannot continue and raises an exception.

In addition an exception will be raised if the component is sent an unexpected parameter, such as a mandatory parameter in an XML input string.

When an exception is raised both an exception number and an exception message are generated.

Message file

From SYSPRO 6.0 issue 010 all messages are stored in a set of text files called MSG???EN.IMP that reside in the program folder

- ??? is a 3 character code representing the logical area of the product - See the table below.

- EN represents the two digit language code passed in the Utilities.Logon method.

Message file | Product area | Set numbers
MSGCOMEN.IMP | Core | 10 - General Messages 11 - Security Messages 12 - Disk error messages 13 - SQL Messages 34 - Report Writer Messages 35 - Business to Business Messages 36 - Archive Messages 38 - Document Flow Manager Messages 40 - XML Parsing Messages 41 - Contact Management Messages 42 - Reporting Services Messages 4? - Reserved for future Core Messages
MSGFINEN.IMP | Financial | 20 - Accounts Payable Messages 21 - Account Receivable Messages 22 - Cash Book Messages 23 - General Ledger messages 33 - Assets Register Messages 5? - Reserved for Future Financial Messages
MSGDISEN.IMP | Distribution | 24 - Inventory Control Messages 25 - Purchase Order Messages 26 - Sales Analysis Messages 27 - Sales Order Messages 32 - Lot Traceability Messages 39 - Landed Cost Tracking 60 - Blanket Sales Orders 61 - Serial Tracking 62 - Multiple Delivery Notes 63 - Trade Promotion Management 64 - Load Planning 6? - Reserved for Future Distribution Messages
MSGMANEN.IMP | Manufacturing | 28 - Bill of Material Messages 29 - Quotation Messages 30 - Work in Progress Messages 31 - Requirements Planning Messages 37 - Engineering Change Control Messages 70 - Projects and Contracts 71 - Product Configurator 72 - Inventory forecasting 7? - Reserved for Future Manufacturing Messages

Note that if a language code other than EN is used but no corresponding message file is found then the system will revert to using the English MSG???EN.IMP file. If a language code of zero/spaces is passed to the Utilities.Logon method then the SYSPRO operator's default language code will be used.

All Message numbers are 6 digits comprising a two digit set number and a four digit sub-message number. For example message number 210004 is set 21 (Accounts Receivable), sub-message 0004 returning the message Customer '%1' not found.

Parameters

The message file can contain parameters, such as %1, so that the messages can be more descriptive. It is important to remember that often a message in e.net is displayed out of context and therefore the messages should be brief but precise. In the above example, simply saying Customer not found when importing a hundred sales orders makes it difficult to correct the problem.

Retrieving messages directly

A business object (COMQER) is available to directly retrieve these standard messages. This allows your application to generate a message. To generate a message you should pass the message number together with the required parameters to be applied to the message (to replace the %1 etc parameters). The expanded message will be returned.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim EncObj As New Encore.Utilities()

Try

UserId = EncObj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = EncObj.Logoff(UserId)

EncObj = Nothing

See also

UserId, Utilities.Logon, Utilities.Logoff, Utilities.GetLogonProfile, COMQER


Business Object

A business object is a piece of SYSPRO business logic encapsulated in such a way as to allow access from the e.net solutions method calls as well as from the regular SYSPRO system.

Many of the e.net methods require you to specify a BusinessObject parameter. For example the generic Query method Query.Query allows you to specify a Query Business Object - such as the Inventory Query object INVQRY.

Each business object conforms to one of the methods supported by the e.net solutions object model. These are:

  • Query.Query

  • Transaction.Build

  • Transaction.Post

  • Setup.Add

  • Setup.Update

  • Setup.Delete

The Business objects are being continually developed and enhanced. See the Support Zone at www.syspro.com for the most up-to-date list of business objects available.

Business objects accept XML input strings (well formed and valid) and return XML Output strings. The methods, such as Query.Query, fully describe the valid XML input including an XSD Schema description and an XML instance for every business object.

e.net Business Object naming conventions

Business objects have a 6 character name.

The first 3 characters consist of a module code. For example INV is the module code for the Inventory Control Module. If the business object is not related to a specific module then the first 3 characters will be COM.

The 4th character contains one of the following:

  • Q - Query business object

  • S - Setup business object

  • T - Transaction Posting business object

  • R - Retrieve/Build business object

  • U - Utility business object

The remaining two characters are a short mnemonic indicating the business object function.

Note that the primary Query in each module contains the 3 character suffix QRY.

For example:

Program name | Method | Notes about program function
INVQRY | Query.Query | Inventory Query business object
INVQAT | Query.Query | Inventory ATP Query business object
ARSSCS | Setup.Add | A/R Customer maintenance Setup business object
INVTSC | Transaction.Post | Inventory Stock Take Transaction Posting business object
SORRSH | Transaction.Build | Sales Order Header Retrieve/Build business object

See also

Object model, UserId, Query.Query, Transaction.Build, Module naming conventions, XML Output


Utilities.Logon

The Utilities.Logon method allows you to connect to e.net solutions.

Remarks

The Logon method must be used before any other e.net method.

The purpose of this method is to log into SYSPRO and, if successful, generate a unique UserId. This UserId is a string that must be used in all subsequent e.net calls to ensure that the same session is referenced.

Use the Utilities.Logoff method to complete the session and release any e.net resources.

Syntax summary

Use of this method

UserId = Utilities.Logon(Operator, OperatorPassword, CompanyId, CompanyPassword, LanguageCode, LogLevel, SysproInstance, XmlIn)

Where

Operator is a SYSPRO operator code

OperatorPassword is the operator's password

CompanyId is a SYSPRO Company id

CompanyPassword is the company password

LanguageCode is the language required for messages

LogLevel is used for developers to assist with debugging

SysproInstance is used where multiple copies of SYSPRO are running on the server

XmlIn is a well formed XML string used to pass any additional parameters

UserId is a returned string that must be used in all subsequent e.net method calls

For a more complete description of the parameters see the section titled Input Parameters below.

Sample ASP.NET code (early binding)

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Fetch Logon profile Information

Dim LoginProfile As String

Try

LoginProfile = Obj.GetLogonProfile(UserId)

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Display as an XML string

Response.Write(LoginProfile)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Sample ASP 3.0 code - late binding

' Logon

Set Obj = Server.CreateObject("Encore.Utilities")

UserId = EncObj.Logon("ADMIN", " ","1", " ", 5, 0, 0, " ")

' Fetch Logon profile Information

LoginProfile = Obj.GetLogonProfile(UserId)

' Logoff and Cancel your current Session

ReturnCode = Obj.Logoff(UserId)

Set Obj = Nothing

Input parameters

Operator (string)

This is a SYSPRO operator code to be used to login to SYSPRO. Depending on the SYSPRO system setup options this may be either a SYSPRO operator code or a Network User login.

OperatorPassword (string)

This is the operator's password. Leave this parameter as spaces if there is no password.

This must exactly match the SYSPRO operator's password.

CompanyId (string)

This is the single character SYSPRO company id. It must be in the range 0-9, A-Z.

If this field is left blank then the default operator's company id will be used - otherwise the entry made here will override the operator's default.

CompanyPassword (string)

This is the company password. Leave this parameter as spaces if there is no password.

This must exactly match the SYSPRO company's password.

LanguageCode (integer)

This defines the language code to be used for messages.

Valid options are:

Spaces - Use operator's default

EN - English (05)

FR - French (07)

ES - Spanish (12)

ZH - Chinese (15)

Leave this parameter as spaces to default to the operator's language.

Note that prior to SYSPRO 6.0 issue 010 you had to pass numeric language codes (shown in brackets). This functionality has been retained for backward compatibility.

LogLevel (integer)

This is a flag indicating if additional information is to be returned.

Valid options are:

0 - normal - this is to be used for normal e.net usage

1 - debug assistance mode - warns if XML strings contain incorrect parameters - normally these are ignored.

SysproInstance (integer)

This is a value indicating the instance of SYSPRO running on the server. If a single instance of SYSPRO is running on the server then set this value to zero.

If you set the SysproInstance between 1 and 9 then this indicates that the appropriate BaseDir? entry will be located from the registry under the e.net solutions key and that instance will be invoked. For example if SysproInstance has a value of 2 then BaseDir2 will be the instance invoked.

XmlIn (string)

This is an optional well formed XML string that can be used to pass extra parameters to the Logon method. If extra parameters are required then the root element must be <Logon>. Leave this parameter as spaces if you do not want to pass additional parameters.

Currently supported elements under the <Logon> element

<Siteid>

You can set the Site id for this Logon using the <Siteid> element.

See the following example XmlIn string:

<Logon>

<Siteid>mysite</Siteid>

</Logon>

<FailWhenAlreadyLoggedIn>

You can set this flag to 'Y' to indicate that if the operator is already logged in then exception 8021 is raised. In this case you can trap the exception and request whether the user wishes to override the existing session or cancel the Logon attempt. If they elect to override the existing session then the same Logon method can be called without the <FailWhenAlreadyLoggedIn> element.

See the following example XmlIn string:

<Logon>

<FailWhenAlreadyLoggedIn>Y</FailWhenAlreadyLoggedIn>

</Logon>

<BuildToPost>

You can set this flag to 'Y' to indicate that the XML output of Build business objects should be modified to be more easily used as XML input to the Post business objects.

See the following example XmlIn string:

<Logon>

<BuildToPost>Y</BuildToPost>

</Logon>

<SourceApp>

You can pass a 30 character string that describes your application.

It is highly recommended that you pass an appropriate <SourceApp> string to allow end-users to be able to identify your application.

See the following example XmlIn string:

<Logon>

<SourceApp>My Application</SourceApp>

</Logon>

This element is new from SYSPRO 6.0 issue 010 2007 onwards and is intended for future use.

For example the eSignature system will provide a mechanism for using a $SourceApp system variable in conditional statements, detail logging and Email notification.

<SystemInformationReqd>

You can set this flag to 'Y' to indicate that the XML output from a Query Business Object is to include a <SystemInformation> node immediately after the root element containing a number of values associated with the current environment.

See the following example XmlIn string:

<Logon>

<SystemInformationReqd>Y</SystemInformationReqd>

</Logon>

See the following example <SystemInformation> node output from the Inventory Query (INVQRY) business object.

<?xml version="1.0" encoding="Windows-1252" ?>

<InvQuery>

<SystemInformation>

<CssStyle />

<Language>EN</Language>

<DecFormat>1</DecFormat>

<DateFormat>01</DateFormat>

<Role>01</Role>

<Version>6.0.016</Version>

<CompanyId>1</CompanyId>

<CompanyName>SYSPRO Outdoors Company</CompanyName>

<OperatorCode>ADMIN</OperatorCode>

<OperatorName>SYSPRO Administrator</OperatorName>

<OperatorGroup>ADMIN</OperatorGroup>

<OperatorEmailAddress />

<OperatorLocation>Head Office</OperatorLocation>

<LocalCurrency>$</LocalCurrency>

<LocalCurrencyDesc>Dollars</LocalCurrencyDesc>

<GlPrdPerYear>12</GlPrdPerYear>

<ReportDate>May 29 2006 04:20 PM</ReportDate>

<UseSeparatorOnReports>Y</UseSeparatorOnReports>

<SeparatorToUse>,</SeparatorToUse>

</SystemInformation>

<StockItem>

<StockCode>B100</StockCode>

<Description>Bicycle</Description>

etc...

</StockItem>

</InvQuery>

<DefaultRole>

From SYSPRO 6.1 extensive use is made of Role Management to define eSignatures, Program access, Activities and Fields, Access control, Workflow etc. An operator is assigned a default role and this is used when using the default Logon method.

However if an operator belongs to more than one Role then when they login to SYSPRO they can switch Roles, in which case the system immediately uses the new Role settings.

When using e.net Solutions you may require to use the Logon method and override the default role to one of the others to which the operator belongs. This is done by using a <DefaultRole> element. It is up to you to ensure that the default role number is valid else the operators original default role will be used.

See the following example XmlIn string:

<Logon>

<DefaultRole>001</DefaultRole>

</Logon>

UserId (string)

The UserId returned is a string identifying the session. This UserId must be used in all subsequent calls to e.net to ensure that the same session is being referenced. It is highly recommended to use the Utilities.Logoff method to close the session to avoid the possibility of additional resources being used by the system.

Requirements

Version: e.net 1.0 and later.

Note that the <FailWhenAlreadyLoggedIn>, <BuildToPost> and <SystemInformationReqd> XmlIn elements are only available with SYSPRO 6.0 issue 010 and later.

Note that the <SourceApp> XmlIn elements are only available with SYSPRO 6.0 issue 010 from 2007 and later.

Note that the <DefaultRole> XmlIn element is only available with SYSPRO 6.1 and later.

See also

UserId, Error Handling, Utilities.Logoff, Utilities.GetLogonProfile, Utilities.Run, Sample Code


Utilities.Logoff

The Utilities.Logoff method allows you to disconnect from e.net solutions.

Remarks

The Utilities.Logoff method should be used to terminate any sessions started with the Utilities.Logon method.

This will finalise and release any resources held by the system.

Syntax summary

Use of this method

ReturnCode = Utilities.Logoff(UserId)

Where

UserId is the UserId returned from the Logon method.

ReturnCode returns the status of the method call

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Fetch Logon profile Information

Dim LoginProfile As String

Try

LoginProfile = Obj.GetLogonProfile(UserId)

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Display as an XML string

Response.Write(LoginProfile)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string - required)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

Output parameters

none

Requirements

Version: e.net 1.0 and later

See also

UserId, Utilities.Logon, Utilities.GetLogonProfile


Utilities.GetLogonProfile

The Utilities.GetLogonProfile method allows you retrieve information about your currently logged in session.

Remarks

This function returns an XML string with a number of details about your current SYSPRO session.

To see a sample of the string returned see the GetLogonProfile.XML sample.

The session must have been created using the Utilities.Logon method.

Also note that you can pass a <SystemInformationReqd> element to the Logon method to have each Business Object output some system information embedded in the XmlOut string. In many cases this is easier and simpler than using the GetLogonprofile method.

Syntax summary

Use of this method

LogonProfile = Utilities.GetLogonProfile(UserId)

Where

UserId is the UserId returned from the Logon method.

LogonProfile is the returned information in XML format

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Fetch Logon profile Information

Dim LogonProfile As String

Try

LogonProfile = Obj.GetLogonProfile(UserId)

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Display as an XML string

Response.Write(LogonProfile)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

Output parameters

LogonProfile (string)

The LogonProfile returned is an XML string containing a number of parameters defining the current session.

Requirements

Version: e.net 1.0 and later

See also

UserId, Utilities.Logon


Utilities.Run

The Utilities.Run method allows you to run a Net Express custom program passing and returning parameters. This method is primarily designed to allow third party developers to invoke one of their own Net Express programs via a COM interface.

Remarks

A sample program called SDKRUN has been supplied as part of the SDK to demonstrate this functionality.

This sample program takes the input parameter string as a stock code and uses this to read the Inventory Master file. The stock description is then returned as an output parameter.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

ReturnString = Utilities.Run(UserId, BusinessObject, Parameter)

Where

UserId is the UserId returned from the Logon method

BusinessObject is the name of an SYSPRO-like program - see SDKRUN as an example

Parameter is a string to be passed to the program

ReturnString is the returned string (often in XML format)

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run SDKRUN and read stock code B100

Dim ReturnString As String

Try

ReturnString = Obj.Run(UserId, "SDKRUN", "B100")

Catch exc As Exception

Response.Write("Unable to run SDKRUN - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write("The Stock Description for item B100 is " & ReturnString)

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

BusinessObject (string)

This is the name of a SYSPRO program to be run. This can be any SYSPRO-like program. See the sample program SDKRUN for an example.

ObjectParameter (string)

This is a string parameter to be passed to the program. Use spaces if you do not require a parameter. This string can be up to 1,000 bytes long. Note that in your SYSPRO program the string will be null terminated.

Output parameters

ReturnString (string)

This is a returned string and can be any length. See SDKRUN for an example about how your SYSPRO program should return values into this string.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, Utilities.Logon


Query.Browse

The Query.Browse method allows you to generically browse on rows from a SYSPRO table.

The generic browse method is designed to be used to provide a browse style interface to a SYSPRO table (the operator can navigate through the table).

The input parameter is an XML string that defines various parameters including the table and initial starting key. The output is returned as an XML Output string. This contains the rows of data returned.

Syntax summary

Use of this method

XmlOut = Query.Browse(UserId, XmlIn)

Where

UserId is the UserId returned from the Logon method.

XmlIn is a well formed XML string providing the table name and initial key to be retrieved

XmlOut is the result as an XML string

The session must have been created using the Utilities.Logon method.

XML input string

Parameters are passed to the method using an XML string - see the following example XML string.

<?xml version="1.0" encoding="Windows-1252"?>

<Browse>

<BrowseName>ArCustomer</BrowseName>

<StartAtKey>2</StartAtKey>

<StartCondition>GE</StartCondition>

<XslStylesheet>browse.xsl</XslStylesheet>

</Browse>

XML input string format

The XML input string must be well formed. It must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

The XML string will consist of:

Element name |  | Notes
<Browse> | Required | This is the root element and is mandatory
<BrowseName> | Required | This defines the name of the browse required. Generally this is the name of the SYSPRO table to be accessed but can be re-configured by a SYSPRO administrator.
<StartAtKey> | Optional | This defines an initial key to be accessed. If blank then the beginning of the table will be used.
<StartCondition> | Optional | This defines whether the browse should proceed forwards or backwards through the table and how the <startatkey> should be used.
<ReturnRows> | Optional | This defines the maximum number of rows to be returned. If not defined then the number configured by the administrator will be used.
<XslStylesheet> | Optional | This defines that the XML returned will contain a pointer to the style sheet specified. This is used to render the XML in a specified style.
<EncoreSetup> | Optional | This indicates to the Generic Browse that an Administrator is re-configuring the browse names and columns. This is only to be used internally by SYSPRO configuration utilities.

There is an XML Schema (COMBRW.XSD) that defines the valid XML input and an example XML instance (COMBRW.XML) that demonstrates an example XML input.

Browse configuration

The Generic Browse uses an XML configuration file that describes the browses available (the browse names), the tables and the columns to be shown together with a browse title and a default number of rows.

There is a default browse configuration file called BROWSE05.XML that resides in the standard SYSPRO base folder. This can be configured using a SYSPRO program (IMPUBR). This allows an administrator to configure the columns to be shown and if required can configure different views of data for each operator.

The generic browse will use the first browse configuration file found from the following list - it is assumed that operator ADMIN is being used with language code 05 (English).

  • settings\Browse05_Oper_ADMIN.xml

  • settings\Browse05_System.xml

  • BROWSE05.XML

By default the browse configuration file contains relatively few columns from each configured table. These can be changed or new ones added using the configuration utility.

Note that if a language code other than 05 is used but no corresponding XML configuration file is found then the generic browse will revert to using language code 05 (English)

Note if the element <EncoreSetup> is set to Y then the generic browse uses the configuration file:

settings\Browse05_Setup_ADMIN.XML

This is only to be used by the configuration utility program.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic fetch returning a warehouse row

Dim Qry As New Encore.Query()

Dim XmlOut As String

' Build an XML string to pass the table name and key

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<Browse>" &_

"<BrowseName>ArCustomer</BrowseName>" &_

"<StartAtKey>1</StartAtKey>" &_

"<StartCondition>GE</StartCondition>" &_

"<XslStylesheet>browse.xsl</XslStylesheet> &_

"</Browse>"

Try

XmlOut = Qry.Browse(UserId, XmlIn)

Catch exc As Exception

Response.Write("Unable to run generic browse - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

XmlIn (string)

This is a well formed XML string providing parameters (browse name and start at key definitions) to the Browse method.

Output parameters

XmlOut (string)

This is the returned data in an XML Output string format. This can be combined with a stylesheet to provide an HTML view of the data.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, XML Output


Query.Fetch

The Query.Fetch method allows you to generically retrieve the columns from a single row from a SYSPRO database.

The generic fetch method returns data in the form of an XML Output string. Input to the generic fetch is also in the form of an XML string.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

XmlOut = Query.Fetch(UserId, XmlIn)

Where

UserId is the UserId returned from the Logon method.

XmlIn is a well formed XML string providing the table name and key to be retrieved

XmlOut is the result as an XML Output string

XML input string

Parameters are passed to the method using an XML string - see the following example XML string.

<?xml version="1.0" encoding="Windows-1252"?>

<Fetch>

<TableName>InvWarehouse</TableName>

<Key>B100</Key>

<OptionalKey1>E</OptionalKey1>

<OptionalKey2/>

<OptionalKey3/>

<OptionalKey4/>

<OptionalKey5/>

<OptionalKey6/>

<OptionalKey7/>

<OptionalKey8/>

<OptionalKey9/>

<OptionalKey10/>

<OptionalKey11/>

<OptionalKey12/>

</Fetch>

XML input string format

The XML input string must be well formed. It must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

The XML string will consist of:

Element name |  | Notes
<Fetch> | Required | This is the root element and is mandatory
<TableName> | Required | This defines the SYSPRO table to be used to retrieve the data. This must be an exact case match of an SYSPRO table name.
<Key> | Required | This defines a primary key column to be accessed. If the key of the table contains multiple columns then this must be the first column.
<OptionalKey1> <OptionalKey2> etc | Optional | This defines additional parts to the primary key to be retrieved. Up to 12 additional key parts can be defined.

There is an XML Schema (COMFCH.XSD) that defines the valid XML input and an example XML instance (COMFCH.XML) that demonstrates an example XML input.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic fetch returning a warehouse row

Dim Qry As New Encore.Query()

Dim XmlOut As String

' Build an XML string to pass the table name and key

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<Fetch>" &_

"<TableName>InvWarehouse</TableName>" &_

"<Key>B100</Key>" &_

"<OptionalKey1>E</OptionalKey1>" &_

"</Fetch>"

Try

XmlOut = Qry.Fetch(UserId, XmlIn)

Catch exc As Exception

Response.Write("Unable to run generic fetch - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

XmlIn (string)

This is a well formed XML string providing parameters (table name and key definitions) to the Fetch method.

Output parameters

XmlOut (string)

This is the returned data in an XML Output string format. This can be combined with a stylesheet to provide an HTML view of the data.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, XML Output


Query.Query

The Query.Query method allows you to generically access a number of Query business objects that return data in the form of an XML Output string. Input to these business objects is also in the form of an XML string.

Using this single method allows the developer to access a rich set of SYSPRO query business objects. Each business object is identified by a name - see the table below.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

XmlOut = Query.Query(UserId, BusinessObject, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a Query business object - see below

XmlIn is a well formed XML string providing the selection and filter logic to be applied

XmlOut is the result as an XML Output string.

XML input string

Parameters are passed to the method using an XML string - see the following example XML string.

<?xml version="1.0" encoding="Windows-1252"?>

<Query>

<Option>

<XslStylesheet>order.xsl</XslStylesheet>

<IncludeCancelledOrders>Y</IncludeCancelledOrders>

<IncludeCompletedOrders>Y</IncludeCompletedOrders>

</Option>

<Filter>

<Branch FilterType='S' FilterValue='AA'/>

<Customer FilterType='S' FilterValue='0000001'/>

<Salesorder FilterType='R' FilterValue='1,100'/>

</Filter>

</Query>

While the general format of this string is common across all Query business objects the actual contents and permitted XML elements may differ from object to object. For this reason a set of XML schemas (XSD files) are documented that describe the permitted parameters and elements for each business object.

XML input string format

The XML input string must be well formed. It must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

The XML string will consist of:

Element name

Notes

<Query>

Required

This is the root element and is mandatory

<Key>

Optional

This defines the primary key to be accessed. Not all business objects require this element.

<Option>

Optional

This element followed by sub-elements (permitted by the business object) provide various options.

Options typically contain a Yes/No element value or a specific piece of information such as an XSL stylesheet to be used. These elements are usually optional, if not passed then a default will be provided. This is indicated in the schema.

<Filter>

Optional

This element followed by sub-elements (permitted by the business object) define filters to be applied to the data returned.

Filters typically allow for a selection of keys to be returned. This can be a Single key, a Range of keys or a List of keys. The range or list are separated by a comma. Filters are optional - if they are omitted the business object will ignore the filter.

Table of Available Query Business Objects

Note that the Schema Reference in this help file contains only a sample of the available business objects. See the Business Object Reference Library on the Support Zone at www.syspro.com for the latest information.

Business Object name | Description | XSD Schema | XML Instance
APSQRY | Supplier Query | APSQRY.XSD | APSQRY.XML
ARSQRY | Customer Query | ARSQRY.XSD | ARSQRY.XML
BOMQRY | BOM Costing Query | BOMQRY.XSD | BOMQRY.XML
COMFND | Generic Find Query | COMFND.XSD | COMFND.XML
COMNOT | Retrieve SYSPRO Notes Query | COMNOT.XSD | COMNOT.XML
COMPRF | Operator Profile Query | COMPRF.XSD | COMPRF.XML
COMQEX | Executive View Query | COMQEX.XSD | COMQEX.XML
COMQER | Retrieve Standard Message Query | COMQER.XSD | COMQER.XML
COMQIB | Message Inbox Query | COMQIB.XSD | COMQIB.XML
COMQMN | Menu Query | {none} | COMQMN.XML
CSHQRY | Cash Book Query | CSHQRY.XSD | CSHQRY.XML
INVQAT | Available to Promise Query | INVQAT.XSD | INVQAT.XML
INVQRP | Inventory Reporting Query | INVQRP.XSD | INVQRP.XML
INVQRY | Inventory Query | INVQRY.XSD | INVQRY.XML
INVQVL | Inventory Valuation Query | INVQVL.XSD | INVQVL.XML
PORQOV | Purchase Order Valuation | PORQOV.XSD | PORQOV.XML
PORQPO | List of Purchase Orders | PORQPO.XSD | PORQPO.XML
PORQRQ | Requisition Query | PORQRQ.XSD | PORQRQ.XML
PORQRY | Purchase Order Query | PORQRY.XSD | PORQRY.XML
PRJQRY | Projects and Contracts Query | PRJQRY.XSD | PRJQRY.XML
QOTQRY | Quotation Query | QOTQRY.XSD | QOTQRY.XML
REPQRY | Report Writer Query | REPQRY.XSD | REPQRY.XML
SORQOV | Sales order value and tax payable Query | SORQOV.XSD | SORQOV.XML
SORQRY | Sales Order Query | SORQRY.XSD | SORQRY.XML
SORQSO | List of Sales Orders | SORQSO.XSD | SORQSO.XML
WIPQJS | WIP Job Status Query | WIPQJS.XSD | WIPQJS.XML
WIPQJV | WIP Job Valuation Query | WIPQJV.XSD | WIPQJV.XML
WIPQRY | WIP Job Query | WIPQRY.XSD | WIPQRY.XML

Summary of available Query Business Objects

This section gives a brief summary of the use of each Query business object.

APSQRY - Supplier Query

The purpose of this business object is to retrieve information about a supplier. This includes Supplier Balances, Invoice information, Registered Invoices, Payments, Goods Received Notes, History of Receipts and Scrap and Reject Information.

ARSQRY - Customer Query

The purpose of this business object is to retrieve information about a customer. This includes customer balances, invoice information, payments and adjustments to the invoices and post-dated checks.

The information retrieved can be used to construct a customer statement including the ability to generate statement information for the current month, prior month 1 or prior month 2. Also note that the age buckets (current, 30, 60, 90 etc days) defined against the A/R Statement format are used. If using the current period (the default) then the current date is used as the statement date else the appropriate prior period end date is used as the statement date.

BOMQRY - BOM Costing Query

The purpose of this business object is to retrieve detailed BOM costing information about a stock code. The query will retrieve information for both materials and operations. This can be for a single or multiple levels.

There are options that allow you to specify routes, version, release, cost basis, Level and Icon information. Version and Release fields are used for ECC controlled items.

COMFND - Generic Find Query

The purpose of this business object is to retrieve rows from a SYSPRO table that match search criteria specified in the XmlIn parameter.

You can specify the table to be searched (only a single table can be specified) and the columns to be returned. In addition you can specify the maximum number of rows to be returned. Then you can specify the search pattern which can include multiple And/Or logic and brackets to specify the precedence.

COMNOT - Retrieve SYSPRO Notes Query

The purpose of this business object is to retrieve notes from the SYSPRO Generic Notes system. These notes are defined against a key field, such as a sales order, and are stored in Rich Text (RTF) format. You can elect to return the notes as plain text (without any formatting) or as Rich Text.

Note that the string returned from this business object is not XML, but consists of just the text.

COMPRF - Operator Profile Query

The purpose of this business object is to retrieve information about the e.net profile defined for an operator. The data returned is information relating to the current ‘logged in’ operator as specified in Operator Maintenance. Information regarding preferred customers and warehouses may be optionally included.

COMQEX - Executive View Query

The purpose of this business object is to return an executive level view of the financial health of your business.

Data returned can include: Inventory Valuation, A/R and A/P balances, Bank balances, Invoices sales, Sales Orders taken, changed or cancelled in the recent past, outstanding Purchase orders, outstanding Sales orders and Work in Progress values.

For more details see the COMQEX topic.

COMQER - Retrieve Standard Message Query

The purpose of this business object is to retrieve standard e.net solutions messages used for informational text or Error Handling. e.net solutions messages are defined in a series of text files and are translatable. You can use this business object to retrieve 1 or more messages. In addition e.net solutions messages may have up to 3 parameters. You should pass these parameters to the business object and they will be replaced before the message is returned.

COMQIB - Message Inbox Query

The purpose of this business object is to retrieve messages from the SYSPRO message Inbox. Messages that have already been read may be optionally retrieved, although the default is to only retrieve new messages.

COMQMN - Menu Query

The purpose of this business object is to retrieve a menu file for the operator, group, company, system.

The business object will look for and retrieve an XML menu file by locating the first matching file in the following sequence relative to the standard SYSPRO base folder:

settings\Menu_Oper_OPER.XML

settings\Menu_Group_GROUP.XML

settings\Menu_Comp_A.XML

settings\Menu_System.XML

Menu.XML

Where OPER is the current Operator code, GROUP is the current Group code, A is the current Company id.

CSHQRY - Cash Book Query

The purpose of this business object is to retrieve information about a bank including the transactions. Transactions may be returned in earliest or latest first sequence. There is an option to include/exclude the multi currency data block information. There are additional options to include/exclude the original A/P or A/R information if the transaction was created from integration of a sub module. Other options allow you to include/exclude reconciled/unreconciled/withdrawals/deposits.

INVQAT - Inventory Available to Promise Query

The purpose of this business object is to calculate the available to promise quantities for a stock code/warehouse combination. There are a number of options that can be submitted to the object to specify what supply and demand is to be used in the calculation and in the information returned. The time fences are also returned.

INVQRP - Inventory Reporting Query

The purpose of this business object is to retrieve information about a stock code and the warehouses in which it is stocked. This object is similar to the Inventory Query Business Object but is designed to provide additional information especially suited to producing business reports.

Information returned includes warehouse information, movements, prices, alternate suppliers, alternate stock codes, stock code exceptions, warehouse exceptions, superseded stock, statistical stock, MPS items, make to order items and warehouse sales history.

The following SYSPRO reports can be produced with the output of this query:

- Aged Inventory Valuation

- Inventory price List

- Warehouse Exception Report

- Inventory Activity Exception Report

- Inventory Superseded/Clearing Stock Report

- Inventory Movement Report

- Kardex report

- Inventory Label Report

INVQRY - Inventory Query

The purpose of this business object is to retrieve information about a stock code and the warehouses in which it is stocked. Information regarding lots, multiple bins and serial numbers may be optionally retrieved.

INVQVL - Inventory Valuation Query

The purpose of this business object is to retrieve valuation information about a stock code and the warehouses and multiple bins in which it is stocked. This value can be based on either the current cost, the last cost, or on FIFO costs. Stock codes not stocked in any warehouse will not be returned.

PORQOV - Purchase Orders Valuation

The purpose of this business object is to retrieve the purchase order value and tax payable for an existing purchase order. If required a purchase order can be passed as an XML string. This allows an order that is still in process to be valued.

PORQPO - List of Purchase Orders

The purpose of this business object is to retrieve a list of purchase orders.

PORQRQ - Requisition Query

The purpose of this business object is to retrieve a list of requisitions either originated by a specific user or routed to a user. Specific requisitions for retrieval may also be specified.

PORQRY - Purchase Order Query

The purpose of this business object is to retrieve a list of detail lines for a specified purchase order. Stocked, non stocked, freight, other charges and comments may be optionally retrieved. In addition, purchase order header information such as supplier name will be returned. Related requisition information can also be returned.

PRJQRY - Projects and Contracts Query

The purpose of this business object is to retrieve all Project and Contract 'contract' or 'job' details. It returns costing information for each attached job and its hierarchy. You may select to return specific information for the hierarchies (e.g. Sales and Adjustment details) as well as select which transactions you would like returned (e.g. Material Issued, Purchase Orders etc.)

QOTQRY - Quotation Query

The purpose of this business object is to retrieve details for a specified Quotation. It returns all line information on the quote as well as details of all offers per quotation line. You may select to return specific quotation line types (e.g. Stocked, Non/Stocked etc) as well as select which offers you would like to see displayed in the line information (e.g. All Offers, Default Offer, Offer1 etc.)

REPQRY - Report Writer Query

The main purpose of this business object is to run a pre-defined report configured for XML using the SYSPRO Report Writer system. The functions supported are:

- Execution of a report and return XML

- Read a report and return the run-time prompt definitions

- Return a list of XML reports in a format that can be used by the generic browse

For more details see the REPQRY topic.

SORQOV - Sales Order Value and Tax payable Query

The purpose of this business object is to retrieve the sales order value and tax payable for an existing sales order. If required a sales order can be passed as an XML string, the value and tax payable on the order will be calculated. This allows an order that is still in process to be valued.

SORQRY - Sales Order Query

The purpose of this business object is to retrieve a list of detail lines for a specified sales order. Stocked, non stocked, freight, other charges and comments may be optionally retrieved. In addition, sales order header information such as customer name and customer purchase order number are returned.

SORQSO - List of Sales Orders

The purpose of this business object is to retrieve a list of sales orders.

WIPQJS - WIP Job Status Query

The purpose of this business object is to retrieve details for jobs in defined status. You can select jobs completed or scheduled to be completed between specified dates. You can also select jobs with the following attributes - jobs on hold, confirmed or unconfirmed, completed, raised for certain customers.

WIPQJV - WIP Job Valuation Query

The purpose of this business object is to calculate and retrieve job valuations. You can select jobs completed or scheduled to be completed between specified dates. You can also select jobs with the following attributes - jobs on hold, confirmed or unconfirmed, completed. You can also select to include sub-jobs, jobs with zero value and jobs with specific job classifications.

WIPQRY - WIP Job Query

The purpose of this business object is to retrieve details for a job. In addition, material transactions, material allocations, purchase orders attached to the job, operation allocations, operation transactions and part booked information may be returned.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic query returning a sales order

Dim Qry As New Encore.Query()

Dim XmlOut As String

' Build an XML string to pass parameters

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<Query>" &_

"<Option>" &_

"<IncludeCancelledOrders>Y</IncludeCancelledOrders>" &_

"<IncludeCompletedorders>Y</IncludeCompletedOrders>" &_

"</Option>" &_

"<Filter>" &_

"<Salesorder FilterType='R' FilterValue='100,200'/>" &_

"</Filter>" &_

"</Query>"

Try

XmlOut = Qry.Query(UserId, "SORQSO", XmlIn)

Catch exc As Exception

Response.Write("Unable to run business object SORQSO - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

BusinessObject (string)

This is the name of a SYSPRO Query business object. Typically Query business objects start with a 3 character module mnemonic and are followed by QRY. For example the Inventory Query is INVQRY. Other queries within the Inventory module will be called INVQ??

XmlIn (string)

This is a well formed XML string providing parameters to the Query method.

Output parameters

XmlOut (string)

This is the returned data in an XML Output string format. This can be combined with a stylesheet to provide an HTML view of the data.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, XML Output


Query.NextKey

The Query.NextKey method allows you to generically retrieve a key alphabetically higher than an existing key. Use of this method together with Query.PreviousKey allows you to provide a next/previous function within your application.

The NextKey method is passed the current key as an XML string and returns the next alphabetically higher key as an XML Output string.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

XmlOut = Query.NextKey(UserId, XmlIn)

Where

UserId is the UserId returned from the Logon method.

XmlIn is a well formed XML string providing the current key

XmlOut is the result as an XML Output string with the next key

XML input string

Parameters are passed to the method using an XML string - see the following example XML string.

<?xml version="1.0" encoding="Windows-1252"?>

<keys>

<TableName>InvWarehouse</TableName>

<Key>B100</Key>

<OptionalKey1>E</OptionalKey1>

<OptionalKey2/>

<OptionalKey3/>

<OptionalKey4/>

<OptionalKey5/>

<OptionalKey6/>

<OptionalKey7/>

<OptionalKey8/>

<OptionalKey9/>

<OptionalKey10/>

<OptionalKey11/>

<OptionalKey12/>

</Keys>

XML input string format

The XML input string must be well formed. It must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

The XML string will consist of:

Element name |  | Notes
<Keys> | Required | This is the root element and is mandatory
<Tablename> | Required | This defines the SYSPRO table to be used to retrieve the data. This must be an exact case match of a SYSPRO table name.
<Key> | Required | This defines a primary key column to be accessed. If the key of the table contains multiple columns then this must be the first column.
<OptionalKey1> <OptionalKey2> etc | Optional | This defines additional parts to the primary key to be retrieved. Up to 12 additional key parts can be defined.

There is an XML Schema (COMKEY.XSD) that defines the valid XML input and an example XML instance (COMKEY.XML) that demonstrates an example XML input.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic fetch returning a warehouse row

Dim Qry As New Encore.Query()

Dim XmlOut As String

' Build an XML string to pass the table name and key

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<Keys>" &_

"<TableName>InvWarehouse</TableName>" &_

"<Key>B100</Key>" &_

"<OptionalKey1>E</OptionalKey1>" &_

"</Keys>"

Try

XmlOut = Qry.NextKey(UserId, XmlIn)

Catch exc As Exception

Response.Write("Unable to get next key - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write("The next key is " & XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

XmlIn (string)

This is a well formed XML string providing the current key.

Output parameters

XmlOut (string)

This is the returned key in an XML Output string format.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, Query.PreviousKey, XML Output


Query.PreviousKey

The Query.PreviousKey method allows you to generically retrieve a key alphabetically lower than an existing key. Use of this method together with Query.NextKey allows you to provide a next/previous function within your application.

The PreviousKey method is passed the current key as an XML string and returns the next alphabetically lower key as an XML Output string.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

XmlOut = Query.PreviousKey(UserId, XmlIn)

Where

UserId is the UserId returned from the Logon method.

XmlIn is a well formed XML string providing the current key

XmlOut is the result as an XML Output string with the previous key

XML input string

Parameters are passed to the method using an XML string - see the following example XML string.

<?xml version="1.0" encoding="Windows-1252"?>

<Keys>

<TableName>InvWarehouse</TableName>

<Key>B100</Key>

<OptionalKey1>E</OptionalKey1>

<OptionalKey2/>

<OptionalKey3/>

<OptionalKey4/>

<OptionalKey5/>

<OptionalKey6/>

<OptionalKey7/>

<OptionalKey8/>

<OptionalKey9/>

<OptionalKey10/>

<OptionalKey11/>

<OptionalKey12/>

</Keys>

XML input string format

The XML input string must be well formed. It must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

The XML string will consist of:

Element name |  | Notes
<Keys> | Required | This is the root element and is mandatory
<Tablename> | Required | This defines the SYSPRO table to be used to retrieve the data. This must be an exact case match of a SYSPRO table name.
<Key> | Required | This defines a primary key column to be accessed. If the key of the table contains multiple columns then this must be the first column.
<OptionalKey1> <OptionalKey2> etc | Optional | This defines additional parts to the primary key to be retrieved. Up to 12 additional key parts can be defined.

There is an XML Schema (COMKEY.XSD) that defines the valid XML input and an example XML instance (COMKEY.XML) that demonstrates an example XML input.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic fetch returning a warehouse row

Dim Qry As New Encore.Query()

Dim XmlOut As String

' Build an XML string to pass the table name and key

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<Keys>" &_

"<TableName>InvWarehouse</TableName>" &_

"<Key>B100</Key>" &_

"<OptionalKey1>E</OptionalKey1>" &_

"</Keys>"

Try

XmlOut = Qry.PreviousKey(UserId, XmlIn)

Catch exc As Exception

Response.Write("Unable to get previous key - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write("The previous key is " & XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

XmlIn (string)

This is a well formed XML string providing the current key information.

Output parameters

XmlOut (string)

This is the returned key in an XML string format.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, Query.NextKey, XML Output


Transaction.Build

The Transaction.Build method allows you to retrieve XML information to assist with the Transaction.Post method.

For example you can call the sales order header build method passing a customer code and a sales order header XML string will be generated. This can then be used to add a sales order using the Transaction.Post method.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

XmlOut = Trn.Build(UserId, BusinessObject, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a SYSPRO Build business object - see below

XmlIn is a well formed XML string providing the basis for the Build

XmlOut is the result as an XML Output string

XML input string

Parameters are passed to the method using an XML string - see the following example XML string.

<?xml version="1.0" encoding="Windows-1252"?>

<Build>

<Parameters>

<Customer>0000001</Customer>

</Parameters>

</Build>

While the general format of this string is common across all query business objects the actual contents and permitted XML elements may differ from object to object. For this reason a set of XML schemas (XSD files) are documented that describe the permitted parameters and elements for each business object.

XML input string format

The XML input string must be well formed. It must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

The XML string will consist of:

Element name |  | Notes
<Build> | Required | This is the root element and is mandatory
<Parameters> | Optional | This defines the primary key to be accessed. Not all business objects require this element.

Table of Available Build Business Objects

Note that the Schema Reference in this help file contains only a sample of the available business objects. See the Business Object Reference Library on the Support Zone at www.syspro.com for the latest information.

Business Object name | Description | XSD Schema | XML Instance
COMRDF | Build Maintenance Defaults | COMRDF.XSD | COMRDF.XML
INVRMO | Build Expense Issue | INVRMO.XSD | INVRMO.XML
QOTRQH | Build Quotation header | QOTRQH.XSD | QOTRQH.XML
SORRBO | Build Back Order Release | SORRBO.XSD | SORRBO.XML
SORRSH | Build Sales Order Header | SORRSH.XSD | SORRSH.XML
SORRSL | Build Sales Order Line | SORRSL.XSD | SORRSL.XML
WIPRLI | Build Labor Issues | WIPRLI.XSD | WIPRLI.XML
WIPRMI | Build Material Issues | WIPRMI.XSD | WIPRMI.XML

Summary of available Build Business Objects

This section gives a brief summary of the use of each build business object.

COMRDF - Build Maintenance Defaults

The purpose of this business object is to build and retrieve defaults for adding various key items. Key items supported include: Customers, Suppliers, Stock codes, Stock code/product classes, Warehouses for a stock code and Supplier ship addresses. The format of the returned XML makes it easy for a developer to access the setup business objects.

INVRMO - Build Expense Issue

The purpose of this business object is to build and retrieve defaults for posting an expense issue inventory movement.

QOTRQH - Build Quotation Header

The purpose of this business object is to build and retrieve defaults for posting a Quotation. A customer and sales order header information can be passed and an XML string is returned containing a Quotation header.

SORRBO - Build Back Order Release

The purpose of this business object is to build and retrieve Sales Order Back Order Release information. If you are denied access to the warehouse, salesperson or branch the information is silently suppressed.

SORRSH - Build Sales Order Header

The purpose of this business object is to build and retrieve a sales order header. A customer is passed to the Retrieve Sales Order Header business object and it returns an XML string containing a sales order header.

SORRSL - Build Sales Order Line

The purpose of this business object is to build and retrieve a sales order line including the current price. A stock code, customer, quantity and other fields are passed to the Retrieve Sales Order Line business object and it returns an XML string containing a sales order line.

The current price returned is based on:

  • The current system date.

  • If the quantity supplied in the XML parameters is zero, then a quantity of ONE will be assumed for price calculations.

  • If the unit of measure is not supplied in the XML Parameters, then the stocking unit of measure will be applied.

WIPRLI - Build Labor Issues

The purpose of this business object is to build Labor Issues and can be used to return information about labor allocations that may be used to issue to a specific job. This information returned can include job, operation, work center, work center rate indicator, machine, run time, setup time, startup time, teardown time, quantity complete and subcontract value.

WIPRMI - Build Material Issues

The purpose of this business object is to build material issues for a job. You can pass a quantity and various flags indicating the types of component to be selected.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic query returning a sales order

Dim Trn As New Encore.Transaction()

Dim XmlOut As String

' Build an XML string to pass parameters

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<Build>" &_

"<Parameters>" &_

"<Customer>" &_

"0000001" &_

"</Customer>" &_

"</Parameters>" &_

"</Build>"

Try

XmlOut = Trn.Build(UserId, "SORRSH", XmlIn)

Catch exc As Exception

Response.Write("Unable to run business object SORRSH - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

BusinessObject (string)

This is the name of a SYSPRO Build business object. Typically SYSPRO build business objects start with a 3 character module mnemonic and are followed by R and another two characters. For example the Sales order header Build Business Object is called SORRSH.

XmlIn (string)

This is a well formed XML string providing parameters to the Build method.

Output parameters

XmlOut (string)

This is the returned data in an XML Output string format.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, XML Output


Transaction.Post

The Transaction.Post method allows you to post transactions to SYSPRO.

Generally you pass an XML string informing the Post method what you want to do and another XML data string with the actual data to be posted.

The more complex Post methods have a Transaction.Build method to assist with building the XML data.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

XmlOut = Trn.Post(UserId, BusinessObject, XmlParameters, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a SYSPRO Post business object - see below

XmlParameters is a well formed XML string providing information to the post method

XmlIn is a well formed XML string providing the data to be posted

XmlOut returns an XML Output string - This indicates the success or failure of the transaction. See below for more details

XML input string(s)

When using the Post method you must pass two XML strings. The first is a set of XML parameters that the Post method will use to determine what to do and the second is an XML string containing the actual data. Note that for some business objects the XmlParameters string is not required.

While the general format of these strings are common across all Post business objects the actual contents and permitted XML elements may differ from object to object. For this reason a set of XML schemas (XSD files) are documented that describe the permitted parameters and elements for each business object.

XML input string format

The XML input strings must be well formed. They must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

Each XmlIn string has a unique root XML element to avoid accidentally passing the wrong XML strings to the wrong method.

XML Output string format

An XML Output string is returned from the Transaction.Post method. The contents of this string contain XML data indicating success or failure of the Transaction posted.

If the transaction failed then the XML string contains a list of errors where XML Element <ErrorDescription> is used to describe the type of error.

If the transaction succeeded then the XML Output string returned will contain the key of the primary transaction posted.

Example XmlOut

The following example XmlOut string is returned when the Post Message to Operator Inbox (COMTIB) Post business object does not have the operator code and subject elements defined - these are mandatory elements.

<?xml version="1.0" encoding="Windows-1252" ?>

<Message Language="05" CssStyle=""
 DecFormat="1" DateFormat="05" Role="01"
 Version="6.0.002">

<Item>

<Operator>

<Value />

<ErrorDescription>Operator '{blank}' not found</ErrorDescription>

</Operator>

<Subject>

<Value />

<ErrorDescription>XML element 'subject' cannot be spaces</ErrorDescription>

</Subject>

</Item>

</Message>

Notice that the XmlOut string can contain multiple messages. Each message is always in the form of:

<Original-xml-element>

<Value>value-passed-to-method</Value>

<ErrorDescription>error-message-text</ErrorDescription>

</Original-xml-element>

Table of Available Post Business Objects

Note that the Schema Reference in this help file contains only a sample of the available business objects. See the Business Object Reference Library on the Support Zone at www.syspro.com for the latest information.

Business Object Name | Description | Root element | XmlParameters XSD Schema / XML Instance | XmlIn XSD Schema / XML Instance
APSTIN | Post A/P Invoices, Debit and Credit Notes | <PostApInvoice> | APSTIN.XSD APSTIN.XML | APSTINDOC.XSD APSTINDOC.XML
APSTRI | Post A/P Registered Invoice | <PostApRegisterInvoice> | APSTRI.XSD APSTRI.XML | APSTRIDOC.XSD APSTRIDOC.XML
ARSTIN | Post A/R Invoices, Debit and Credit Notes | <PostArInvoices> | ARSTIN.XSD ARSTIN.XML | ARSTINDOC.XSD ARSTINDOC.XML
ARSTPY | Post A/R Payment, Adjustment and Miscellaneous receipt. | <PostArPayment> | ARSTPY.XSD ARSTPY.XML | ARSTPYDOC.XSD ARSTPYDOC.XML
COMTIB | Post Message to Operator Inbox | <Message> | {none} | COMTIBDOC.XSD COMTIBDOC.XML
CSHTWD | Post a Cash Book Deposit or Withdrawal | <PostCbDepositsWithdrawals> | CSHTWD.XSD CSHTWD.XML | CSHTWDDOC.XSD CSHTWDDOC.XML
INVTMA | Post an Inventory Adjustment | <PostInvAdjustments> | INVTMA.XSD INVTMA.XML | INVTMADOC.XSD INVTMADOC.XML
INVTMB | Post Inventory Bin Transfer | <PostInvBinTransfers> | INVTMB.XSD INVTMB.XML | INVTMBDOC.XSD INVTMBDOC.XML
INVTMC | Post Inventory Cost Changes | <PostInvCostChange> | INVTMC.XSD INVTMC.XML | INVTMCDOC.XSD INVTMCDOC.XML
INVTME | Post Inventory Expense Issues | <PostInvExpenseIssues> | INVTME.XSD INVTME.XML | INVTMEDOC.XSD INVTMEDOC.XML
INVTMI | Post an Inventory Warehouse Transfer In | <PostInvWhTransferIn> | INVTMI.XSD INVTMI.XML | INVTMIDOC.XSD INVTMIDOC.XML
INVTMM | Post an Inventory Cost Modification | <PostInvCostModification> | INVTMM.XSD INVTMM.XML | INVTMMDOC.XSD INVTMMDOC.XML
INVTMN | Post an Inventory Goods in Transfer In | <PostInvGitWhTransferIn> | INVTMN.XSD INVTMN.XML | INVTMNDOC.XSD INVTMNDOC.XML
INVTMO | Post an Inventory Warehouse Transfer Out | <PostInvWhTransferOut> | INVTMO.XSD INVTMO.XML | INVTMODOC.XSD INVTMODOC.XML
INVTMR | Post an Inventory Receipt | <PostInvReceipts> | INVTMR.XSD INVTMR.XML | INVTMRDOC.XSD INVTMRDOC.XML
INTTMT | Post an Inventory Goods in Transit Transfer Out | <PostInvGitWhTransferOut> | INVTMT.XSD INVTMT.XML | INVTMTDOC.XSD INVTMTDOC.XML
INVTSC | Post to stock take | <StockTake> | INVTSC.XSD INVTSC.XML | INVTSCDOC.XSD INVTSCDOC.XML
INVTSR | Post a Transaction against Serial Numbers | <PostInvSerialTransactions> | INVTSR.XSD INVTSR.XML | INVTSRDOC.XSD INVTSRDOC.XML
INVTSU | Post an Inventory Stock Take Confirmation | <PostStockTakeConfirmation> | {none} | INVTSUDOC.XSD INVTSUDOC.XML
MRPTBS | Post a Build Schedule | <PostBuildSchedule> | MRPTBS.XSD MRPTBS.XML | MRPTBSDOC.XSD MRPTBSDOC.XML
MRPTFO | Post a Forecast | <PostForecastMaintenance> | MRPTFO.XSD MRPTFO.XML | MRPTFODOC.XSD MRPTFODOC.XML
PORTGR | Post GRN details | <PostGrnDetails> | PORTGR.XSD PORTGR.XML | PORTGRDOC.XSD PORTGRDOC.XML
PORTOI | Post a Purchase Order | <PostPurchaseOrders> | PORTOI.XSD PORTOI.XML | PORTOIDOC.XSD PORTOIDOC.XML
PORTOR | Post a Purchase Order Receipt | <PostPurchaseOrderReceipts> | PORTOR.XSD PORTOR.XML | PORTORDOC.XSD PORTORDOC.XML
PORTRH | Change the hold/release status of a Requisition | <PostReqHold> | PORTRH.XSD PORTRH.XML | PORTRHDOC.XSD PORTRHDOC.XML
PORTRQ | Post a Requisition | <PostRequisition> | PORTRQ.XSD PORTRQ.XML | PORTRQDOC.XSD PORTRQDOC.XML
PORTRR | Route a Requisition to a User | <PostReqRoute> | {none} | PORTRRDOC.XSD PORTRRDOC.XML
QOTTQI | Post a Quotation | <PostQuotation> | QOTTQI.XSD QOTTQI.XML | QOTTQIDOC.XSD QOTTQIDOC.XML
SORTBO | Post a Sales Order Back Order Release | <PostSorBackOrderRelease> | SORTBO.XSD SORTBO.XML | SORTBODOC.XSD SORTBODOC.XML
SORTIC | Create Invoice from a Sales Order | <PostSalesOrderInvoice> | SORTIC.XSD SORTIC.XML | SORTICDOC.XSD SORTICDOC.XML
SORTOI | Post a Sales Order | <SalesOrders> | SORTOI.XSD SORTOI.XML | SORTOIDOC.XSD SORTOIDOC.XML
SORTOS | Change Sales Order Status | <PostSorOrderStatus> | SORTOS.XSD SORTOS.XML | SORTOSDOC.XSD SORTOSDOC.XML
WIPTAI | Post WIP Inspection Accept into stock | <PostWIPInspectAccept> | WIPTAI.XSD WIPTAI.XML | WIPTAIDOC.XSD WIPTAIDOC.XML
WIPTII | Post WIP Inspection Quantity Maintenance | <PostWIPInspected> | WIPTII.XSD WIPTII.XML | WIPTIIDOC.XSD WIPTIIDOC.XML
WIPTJB | Add, Update or Delete a Job | <PostJob> | WIPTJB.XSD WIPTJB.XML | WIPTJBDOC.XSD WIPTJBDOC.XML
WIPTJC | Post WIP Job Closure | <PostJobClosure> | WIPTJC.XSD WIPTJC.XML | WIPTJCDOC.XSD WIPTJCDOC.XML
WIPTJL | Post WIP Operations | <PostLabourAllocations> | WIPTJL.XSD WIPTJL.XML | WIPTJLDOC.XSD WIPTJLDOC.XML
WIPTJM | Post WIP Material Allocations | <PostMaterialAllocations> | WIPTJM.XSD WIPTJM.XML | WIPTJMDOC.XSD WIPTJMDOC.XML
WIPTJR | Post WIP Job Receipts | <PostJobReceipts> | WIPTJR.XSD WIPTJR.XML | WIPTJRDOC.XSD WIPTJRDOC.XML
WIPTLP | Post WIP Labor and non-productive time to a job | <PostLabour> | WIPTLP.XSD WIPTLP.XML | WIPTLPDOC.XSD WIPTLPDOC.XML
WIPTMI | Post WIP Job Specific Issues | <PostMaterial> | WIPTMI.XSD WIPTMI.XML | WIPTMIDOC.XSD WIPTMIDOC.XML
WIPTPB | Post WIP Part Billings | <PostPartBillings> | WIPTPB.XSD WIPTPB.XML | WIPTPBDOC.XSD WIPTPBDOC.XML
WIPTSI | Post WIP Inspection Scrap | <PostWIPInspectionScrap> | WIPTSI.XSD WIPTSI.XML | WIPTSIDOC.XSD WIPTSIDOC.XML
WIPTSU | Attaches sub jobs to a master job | <PostMasterSubJob> | WIPTSU.XSD WIPTSU.XML | WIPTSUDOC.XSD WIPTSUDOC.XML
Available Post Business Objects

The following section describe the available Post business objects.

APSTIN - Post A/P Invoices, Debit and Credit Notes

The purpose of this business object is to post supplier Invoices, Debit notes, Credit notes and Adjustments. This information includes details of the transaction including the G/L distribution entries.

The XmlOut parameter returns the key of the items added. This includes the Supplier and Invoice/Debit note/Credit note number.

APSTRI - Post A/P Registered Invoice

The purpose of this business object is to post an A/P Registered Invoice. This allows you to record an invoice that has not yet been approved.

The XmlOut parameter returns the Registered invoice numbers added.

ARSTIN - Post A/R Invoices, Debit and Credit Notes

The purpose of this business object is to post customer Invoices, Debit notes and Credit notes. The Debit and Credit notes can be applied to a existing invoice of can be standalone documents.

The XmlOut parameter returns the key of the items added. This includes the Customer and Invoice/Debit note/Credit note number.

ARSTPY - Post A/R Payments, Adjustments and Miscellaneous Receipts

The purpose of this business object is to post customer payments, adjust invoice details and post miscellaneous receipts. The payment function handles specific 'manual' payments against a SYSPRO invoice and automatic payments.

The XmlOut parameter returns the key of the journal added. This includes the Customer and Year, Month and Journal number.

COMTIB - Post Message to Operator Inbox

The purpose of this business object is to post a new message to the SYSPRO Operator Message Inbox. An operator code, the message text and a message type are passed to this method. In addition, a SYSPRO program may optionally be passed to be run with a parameter.

For example, this could be used to pass a message that the quantity on hand is running low for a stock code and that when the operator clicks on the message they can be taken directly to the Inventory Query for the affected stock code.

When these messages are generated automatically, it is possible to define a flag to ensure that duplicate messages are not generated. Also the message type can be used to group types of messages.

The XmlParameter parameter for the method call is unused and should be set to spaces.

The XmlOut parameter returns the key of the added message.

CSHTWD - Post Cash Book Deposit or Withdrawal

The purpose of this business object is to post a Deposit or Withdrawal to Cash Book. You can add new transactions or adjust existing ones. You can also use this business object to reconcile or unreconcile existing transactions.

The XmlOut parameter returns the bank, transaction year and month, journal and entry number and transaction date and time for successful transactions.

INVTMB - Post Inventory Bin Transfer

The purpose of this business object is to post Inventory Bin Transfers. This allows you to record the transfer of items from one bin to another.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTMC - Post Inventory Cost Changes

The purpose of this business object is to post Inventory Cost Changes.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTME - Post Inventory Expense Issues

The purpose of this business object is to post Inventory Issues. This allows you to issue stock without allocating the items against a purchase order or job.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTMI - Post Inventory Warehouse Transfer In

The purpose of this business object is to post Inventory Warehouse Transfer In transactions. This allows items in transit to be received into the destination warehouse.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTMM - Post Inventory Cost Modification

The purpose of this business object is to post an Inventory Cost Modification transaction.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTMN - Post Inventory Goods in Transfer - Transfer In

The purpose of this business object is to post an Inventory Goods in Transfer - Transfer In transaction.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTMO - Post Inventory Warehouse Transfer Out

The purpose of this business object is to post an Inventory Warehouse Transfer Out transaction. There are three basic functions supported - they are:

Out - Stock is transferred out of the source warehouse. These items remain in transit until a transfer is recorded into a destination warehouse.

Out/No destination - Stock is transferred out of the source warehouse and no destination warehouse is involved.

Immediate -Stock is transferred out of the source warehouse and received into the destination warehouse in a single transaction.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTMR - Post Inventory Receipt

The purpose of this business object is to post an Inventory Receipt transaction.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTMT - Post Inventory GIT Transfers Out

The purpose of this business object is to post an Inventory Goods in Transit Transfer Out transaction.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

INVTSC - Post to Stock take

The purpose of this business object is to post information to the stock take capture tables. When a stock take is in progress you can use this business object to capture Stock items, quantities, lots, bins, serials and other information.

INVTSR - Post a Transaction against a Serial Number

The purpose of this business object is to post a transaction against a Serial Number.

The XmlOut parameter returns the Serial number, Transaction date, Line Number and Warehouse for successful transactions. In addition the Transaction code and Item number is returned.

INVTSU - Post an Inventory Stock Take Confirmation

The purpose of this business object is to confirm details of the stock take capture process and to update the live inventory files with the captured quantities.

The XmlOut parameter returns the Inventory Journal number for successful transactions.

MRPTBS - Post a BuildSchedule

The purpose of this business object is to add, change and delete Build schedules.

The XmlOut parameter returns the stock code, warehouse and line numbers affected.

MRPTFO - Post a Forecast

The purpose of this business object is to add, change and delete Forecasts.

The XmlOut parameter returns the stock code, warehouse and line numbers affected.

PORTGR - Post GRN Details

The purpose of this business object is to create GRN details when GRN Suspence is required. This function works similarly to the standard SYSPRO GRN Detail import.

A validation phase is performed first and if no errors are found, the purchase orders are imported.

The XmlOut parameter returns a list of GRN numbers added.

PORTOI - Post a Purchase Order

The purpose of this business object is to import purchase orders into SYSPRO.

A validation phase is performed first and if no errors are found, the purchase orders are imported.

The XmlOut parameter returns a list of purchase orders added.

PORTOR - Post Purchase Order Receipts

The purpose of this business object is to post a Purchase Order Receipt. All information required for receiving a purchase order can be specified including multiple bins, serial numbers and lot information.

The XmlOut parameter returns the Inventory journal numbers added.

PORTRH - Change the Hold/Release Status of a Requisition

The purpose of this business object is to change the Hold or Release status of a requisition line or all lines on a requisition. You must specify a reason when placing a requisition on hold.

PORTRQ - Post a Requisition

The purpose of this business object is to add a new Requisition or change an existing Requisition. You can also add lines to an existing requisition. Requisition and/or Purchase order notes can be supplied. The Requisition can be linked to a purchase order or a job.

The XmlOut parameter returns a list of requisition numbers added.

PORTRR - Route a Requisition to a User

The purpose of this business object is to route a requisition line or all lines on a requisition to another user. You can add associated notes along with the routing.

QOTTQI - Post a Quotation

The purpose of this business object is to post a Quotation. This can be used to add a new quotation or maintain an existing one.

SORTBO - Post a Sales Order Back Order Release

The purpose of this business object is to release a Sales Order from Back Order. Details of the sales order and line number to be released must be supplied together with the quantity to be released.

SORTIC - Create an Invoice from a Sales Order

The purpose of this business object is to generate an A/R invoice from a Sales Order.

All the relevant data files are updated during this transaction.

The XmlOut parameter returns a list of sales orders updated and invoices generated. In addition a list of the sales transaction register numbers are also returned.

SORTOI - Post a Sales Order

The purpose of this business object is to import sales orders into SYSPRO.

A validation phase is performed first and if no errors are found, the sales orders are imported.

The XmlOut parameter returns a list of sales orders added.

SORTOS - Change Sales Order Status

The purpose of this business object is allow the status of a Sales Order to be changed.

WIPTAI - Post WIP Inspection - Accept into Stock

There are several business objects that allow you to process two-stage receipts for goods in Work in Progress.

This two-stage receipt facility enables you to first receipt stock into an inspection file after completing your job. While in inspection, the goods may be inspected, accepted into stock, posted back to Work in Progress for rework or scrapped entirely.

This object allows you to Accept items into Stock.

WIPTII - Post WIP Inspection - Inspect Quality Maintenance

There are several business objects that allow you to process two-stage receipts for goods in Work in Progress.

This two-stage receipt facility enables you to first receipt stock into an inspection file after completing your job. While in inspection, the goods may be inspected, accepted into stock, posted back to Work in Progress for rework or scrapped entirely.

This object allows you to Inspect items.

WIPTJB - Add, Update and Delete Jobs

The purpose of this business object is to add, update or delete Jobs.

The Add a job function is limited to adding live jobs. The SYSPRO MRP module is used to take snapshots and add/maintain suggested jobs.

When Maintaining jobs you can update live, suggested and snapshot jobs.

The XmlOut parameter returns the key of the item added/changed/deleted. This includes the job number and optionally the operation number.

WIPTJC - WIP Job Closure

The purpose of this business object is to close Work in Progress Jobs.

The XmlOut parameter returns the key of the job closed. This includes the main job and any sub-jobs.

WIPTJL - Post WIP Operations

The purpose of this business object is to add, update or delete WIP Labor Operations for one or more jobs.

The XmlOut parameter returns the key of the item added. This includes the job number and operation number.

WIPTJM - Post WIP Material Allocations

The purpose of this business object is to add, update or delete WIP Material Allocations for one or more jobs.

The XmlOut parameter returns the key of the item added. This includes the job number, stock code, warehouse and line number.

WIPTJR - Post WIP Job Receipt

The purpose of this business object is to receive 'stocked' finished parts into stock that have been manufactured against a job. If the job is linked to a Sales Order then the quantity received can be used to update the Sales Order line. If the job is a sub-job then the quantity will be automatically issued to the master job against the material allocation. Serial numbers, bin locations and lot numbers can be specified when applicable.

The XmlOut parameter returns the key of the job elements affected and the journals added.

WIPTLP - Post WIP Labor and non-productive time to a job

The purpose of this business object is to post productive or non-productive time to a job.

The XmlOut parameter returns the key of the journal added. This includes the year, month and journal and entry number.

WIPTMI - Post WIP Job Specific Issues

The purpose of this business object is to issue the component parts to a confirmed job.

As components are issued, the inventory quantity on hand is automatically reduced and the work in progress allocations updated.

The XmlOut parameter returns the key of the journal added. This includes the year, month and journal, entry number and warehouse.

WIPTPB - Post WIP Part Billings

The purpose of this business object is to invoice a customer based on work completed for a non-stocked job.

The work in progress value is reduced, You may distribute the invoice amount across multiple ledger codes and you may post this information to a Sales Order.

The XmlOut parameter returns the key of the journal added. This includes the year, month and journal and entry number.

WIPTSI - Post WIP Inspection - Scrap

There are several business objects that allow you to process two-stage receipts for goods in Work in Progress.

This two-stage receipt facility enables you to first receipt stock into an inspection file after completing your job. While in inspection, the goods may be inspected, accepted into stock, posted back to Work in Progress for rework or scrapped entirely.

This object allows you to Scrap an item.

WIPTSU - Attach sub jobs to master jobs

The purpose of this business object is to attach sub jobs to master jobs.

Sample ASP.NET code

' Sample code to Post a message to the SYSPRO Message Inbox

'

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic query returning a sales order

Dim Trn As New Encore.Transaction()

Dim XmlOut As String

' Build an XmlParameter XML string to pass parameters

Dim XmlParameter As String

XmlParameter = "<?xml version=""1.0"" encoding=""Windows-1252""?>"

' Build an XmlIn XML string to pass data to be posted

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<Message>" &_

"<Item>" &_

"<Companyid>A</Companyid>" &_

"<Operator>ADMIN</Operator>" &_

"<Date/>" &_

"<Time/>" &_

"<MessageType>ENET</MessageType>" &_

"<Subject>Stock on hand low for item B100</Subject>" &_

"<FromOperator/>" &_

"<FromName/>" &_

"<ProgramToRun>INVPEN</ProgramToRun>" &_

"<ProgramParameters>B100</ProgramParameters>" &_

"<PreventDuplicate/>" &_

"</Item>" &_

"</Message>"

Try

XmlOut = Trn.Post(UserId, "COMTIB", XmlParameters, XmlIn)

Catch exc As Exception

Response.Write("Unable to run business object COMTIB - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

BusinessObject (string)

This is the name of a SYSPRO Post business object. Typically SYSPRO post business objects start with a 3 character module code mnemonic and are followed by T and another two characters. For example the Sales Order Post Business Object is called SORTOI.

XmlParameters (string)

This is a well formed XML string providing parameters to the Post method. See the description of the business object for valid XML elements.

XmlIn (string)

This is a well formed XML string providing the actual data to be processed by the Post method. See the description of the business object for the valid XML elements.

Output parameters

XmlOut (string)

This is an returned XML Output string. The contents of this string contain XML data indicating success or failure of the Transaction posted.

If the transaction failed then the XML string contains a list of errors where XML Element <ErrorDescription> is used to describe the type of error.

If the transaction succeeded then the XML data returned will contain the key of the primary transaction posted.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, Transaction.Build, XML Output


Setup.Add

The Setup.Add method allows you to add data to the SYSPRO data structures. The Setup.Add method can be used to add single or multiple items with a single call. There are a number of Setup business objects that accept an XML string passing the data to be added. Each business object is identified by a name - see the table below.

The Setup.Add method can be used as the basis for an import function.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

ReturnCode = Setup.Add(UserId, BusinessObject, XmlParameters, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a SYSPRO Setup business object - see below

XmlParameters is a well formed XML string providing details of the function to be performed

XmlIn is a well formed XML string providing the data to be added

ReturnCode returns the status of the method call

XML input string(s)

When using the Add method you must pass two XML strings. The first is a set of XML parameters that the Add method will use to determine what to do and how to handle error conditions and the second is an XML string containing the actual data.

When the Add methods parses the XML elements to be added any elements not supplied will have a default value applied.

While the general format of these strings are common across all Add business objects the actual contents and permitted XML elements may differ from object to object. For this reason a set of XML schemas (XSD files) are documented that describe the permitted parameters and elements for each business object.

XML input string format

The XML input strings must be well formed. They must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

Each XmlIn string has a unique root XML element to avoid accidentally passing the wrong XML strings to the wrong business object. The root element is the word Setup followed by the Table name. For example to add data to the ArCustomer table the root element is <SetupArCustomer>.

XML Output string format

An XML Output string is returned from the Setup.Add method. The contents of this string contain XML data indicating success or failure of the data being added.

If the addition failed then the XML string contains a list of errors where XML Element <ErrorDescription> is used to describe the type of error.

In addition there is a summary of the results of the Add method indicating the number of items read from the XML string and the number of failures.

Example XmlOut

The following example XmlOut string is returned when the Setup.Add method is used to attempt to add three customers (ARSSCS business object) one of which already exists.

<?xml version="1.0" encoding="Windows-1252" ?>

<SetupArCustomer Language="05"
 CssStyle="" DecFormat="1" DateFormat="01"
 Role="01">

<item>

<key>

<Customer>0000002</Customer>

</key>

<Customer>

<Value>0000002</Value>

<ErrorDescription>Duplicate key '0000002' on 'ArCustomer'</ErrorDescription>

</Customer>

</item>

<StatusOfItems>

<RecordsRead>3</RecordsRead>

<RecordsInvalid>1</RecordsInvalid>

</StatusOfItems>

</SetupArCustomer>

Notice that the XmlOut string can contain multiple messages. Each message is always in the form of:

<Key>

<Key-Column-Name>key-value</Key-Column-Name>

</Key>

<Item-Name>

<Value>value-passed-to-method</Value>

<ErrorDescription>error-message-text</ErrorDescription>

</Item-Name>

Table of Available Add Business Objects

Note that the Schema Reference in this help file contains only a sample of the available business objects. See the Business Object Reference Library on the Support Zone at www.syspro.com for the latest information.

Business Object Name | Description | Root element | XmlParameters XSD Schema / XML Instance | XmlIn XSD Schema / XML Instance
ARSSCS | Add Customer | <SetupArCustomer> | ARSSCS.XSD ARSSCS.XML | ARSSCSDOC.XSD ARSSCSDOC.XML
BOMSMC | Add BOM Machine | <SetupBomMachine> | BOMSMC.XSD BOMSMC.XML | BOMSMCDOC.XSD BOMSMCDOC.XML
BOMSRO | Add BOM Routing | <SetupBomRouting> | BOMSRO.XSD BOMSRO.XML | BOMSRODOC.XSD BOMSRODOC.XML
BOMSSN | Add BOM Narration | <SetupBomNarration> | {none} | BOMSSN.XSD BOMSSN.XML
BOMSST | Add BOM Structure | <SetupBomStructure> | BOMSST.XSD BOMSST.XML | BOMSSTDOC.XSD BOMSSTDOC.XML
BOMSWC | Add BOM Work Center | <SetupBomWorkCentre> | BOMSWC.XSD BOMSWC.XML | BOMSWCDOC.XSD BOMSWCDOC.XML
COMSFM | Add a Custom Form field to a key field | <SetupCustomForm> | COMSFM.XSD COMSFM.XML | COMSFMDOC.XSD COMSFMDOC.XML
INVSPR | Add Price to a stock code | <SetupInvPrice> | INVSPR.XSD INVSPR.XML | INVSPRDOC.XSD INVSPRDOC.XML
INVSSR | Add a Serial Number to a stock code | <SetupInvSerialHead> | INVSSR.XSD INVSSR.XML | INVSSRDOC.XSD INVSSRDOC.XML
INVSST | Add Stock Code | <SetupInvMaster> | INVSST.XSD INVSST.XML | INVSSTDOC.XSD INVSSTDOC.XML
INVSWS | Add Warehouse to a stock code | <SetupInvWarehouse> | INVSWS.XSD INVSWS.XML | INVSWSDOC.XSD INVSWSDOC.XML
QOTSNS | Add Quotation Non-stocked codes | <SetupQotNonStock> | QOTSNS.XSD QOTSNS.XML | QOTSNSDOC.XSD QOTSNSDOC.XML
QOTSRO | Add Routing for Estimates for non-stocked items | <SetupQotRouting> | QOTSRO.XSD QOTSRO.XML | QOTSRODOC.XSD QOTSRODOC.XML
QOTSST | Add Component for Estimates for non-stocked items | <SetupQotStructure> | QOTSST.XSD QOTSST.XML | QOTSSTDOC.XSD QOTSSTDOC.XML
Available Add Business Objects

The following section describe the available Add business objects.

ARSSCS - A/R Customer Setup

Use this business object to add a customer. Any columns not passed will use the company defaults defined in the Customer maintenance program.

BOMSMC - BOM Machine Setup

Use this business object to add a BOM Machine.

BOMSRO - BOM Routing Setup

Use this business object to add a BOM Routing - list of operations - for a parent part. Note that this object does not allow components to be added. See BOMSST.

The XmlOut parameter contains the parent part together with the revision and release information.

BOMSSN - BOM Narration Setup

Use this business object to add narrations. The following narration types can be added:

- Job narration

- WIP material narration

- WIP operation narration

- BOM structure narration

- BOM operation narration

- Estimate structure narration

See the schema BOMSSN.XSD for the available narration types and how to define the key fields.

BOMSST - BOM Structure Setup

Use this business object to add a BOM structure. This allows a parent / component structure to be added. Note that this object does not allow operations to be added. See BOMSRO.

BOMSWC - BOM Work Center Setup

Use this business object to add a BOM Work Center.

COMSFM - Custom Form Setup

Use this business object to add a Custom Form field to an existing key field. This allows a Custom Form field that has been pre-defined (name, description, type, length etc) to be added to an existing key field - such as a stock code.

INVSPR - Inventory Price Code Setup

Use this business object to add a price code to a stock code.

INVSSR - Inventory Serial Number Setup

Use this business object to add a serial number to a stock code.

INVSST - Inventory Stock Code Setup

Use this business object to add a stock code. Any columns not passed will use either the company defaults defined in the Stock code maintenance program or the defaults defined at product class level. An element in INVSST.XML can be used to choose the default selection.

INVSWS - Inventory Warehouse Setup

Use this business object to add a warehouse to a stock code. Any columns not passed will use either the company defaults defined in the Stock code maintenance program or the defaults defined at product class level. An element in INVSWS.XML can be used to choose the default selection.

QOTSNS - Quotation Non-stocked Maintenance Setup

Use this business object to add non-stocked codes that will be used for the non-stocked items within quotations.

QOTSRO - Quotation Routing Setup

Use this business object to add routing information for Estimates of non-stocked items.

QOTSST - Quotation Component Setup

Use this business object to add component information for Estimates of non-stocked items.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic query returning a sales order

Dim Setup As New Encore.Setup()

Dim XmlOut As String

' Build an XML string to pass parameters

Dim XmlParameters As String

XmlParameters =

"<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<SetupArCustomer>" &_

"<Parameters>" &_

"<IgnoreWarnings>N</IgnoreWarnings>" &_

"<ApplyIfEntireDocumentValid>Y</ApplyIfEntireDocumentValid>" &_

"<ValidateOnly>N</ValidateOnly>" &_

"<DeletePassword/>" &_

"</Parameters>" &_

"</SetupArCustomer>"

' Build an XML string to add a customer

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<SetupArCustomer>" &_

"<Item/>" &_

"<Key" &_

"<Customer>0000002</Customer>" &_

"</Key> &_

"<Name>Bikes and Blades - North</Name>" &_

"<Branch>20</Branch>" &_

"<Salesperson>200</Salesperson>" &_

"</Item>" &_

"</SetupArCustomer>"

Try

XmlOut = Setup.Add(UserId, "ARSSCS", XmlParameters, XmlIn)

Catch exc As Exception

Response.Write("Unable to run business object ARSSCS - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

BusinessObject (string)

This is the name of a SYSPRO Setup business object. Typically SYSPRO setup business objects start with a 3 character module code mnemonic and are followed by S and another two characters. For example the Customer Setup Business Object is called ARSSCS.

XmlParameters (string)

This is a well formed XML string providing parameters to the Add method. You can indicate that you only want to validate the items and you can indicate that only if all the validations succeed will any data be added.

XmlIn (string)

This is a well formed XML string providing the data to be added. Generally any data not supplied will have a default applied.

Output parameters

ReturnCode (string)

This is a return status code.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML


Setup.Update

The Setup.Update method allows you to change data in the SYSPRO data structures. There are a number of Setup business objects that accept an XML string passing the data to be update. Each business object is identified by a name - see the table below.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

ReturnCode = Setup.Update(UserId, BusinessObject, XmlParameters, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a SYSPRO Setup business object - see below

XmlParameters is a well formed XML string providing details of the function to be performed

XmlIn is a well formed XML string providing the data to be updated

ReturnCode returns the status of the method call

XML input string(s)

When using the Update method you must pass two XML strings. The first is a set of XML parameters that the Update method will use to determine what to do and how to handle error conditions and the second is an XML string containing the actual data.

When the Update methods parses the XML elements to be updated only elements supplied will be updated. No other column values will be changed. For example if you just supply the Customer's telephone number only the phone numbers will be updated.

While the general format of these strings are common across all Update business objects the actual contents and permitted XML elements may differ from object to object. For this reason a set of XML schemas (XSD files) are documented that describe the permitted parameters and elements for each business object.

XML input string format

The XML input strings must be well formed. They must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

Each XmlIn string has a unique root XML element to avoid accidentally passing the wrong XML strings to the wrong business object. The root element is the word Setup followed by the Table name. For example to update data in the ArCustomer table the root element is <SetupArCustomer>.

XML Output string format

An XML Output string is returned from the Setup.Update method. The contents of this string contain XML data indicating success or failure of the data being changed.

If the update failed then the XML string contains a list of errors where XML Element <ErrorDescription> is used to describe the type of error.

In addition there is a summary of the results of the Update method indicating the number of items read from the XML string and the number of failures.

Example XmlOut

The following example XmlOut string is returned when the Setup.Update method is used to attempt to update three customers (ARSSCS business object) one of which does not exist.

<?xml version="1.0" encoding="Windows-1252" ?>

<SetupArCustomer Language="05"
 CssStyle="" DecFormat="1" DateFormat="01"
 Role="01">

<item>

<key>

<Customer>0000002</Customer>

</key>

<Customer>

<Value>0000002</Value>

<ErrorDescription>Key '0000002' not found on 'ArCustomer'</ErrorDescription>

</Customer>

</item>

<StatusOfItems>

<RecordsRead>3</RecordsRead>

<RecordsInvalid>1</RecordsInvalid>

</StatusOfItems>

</SetupArCustomer>

Notice that the XmlOut string can contain multiple messages. Each message is always in the form of:

<Key>

<Key-Column-Name>key-value</Key-Column-Name>

</Key>

<Item-Name>

<Value>value-passed-to-method</Value>

<ErrorDescription>error-message-text</ErrorDescription>

</Item-Name>

Table of Available Update Business Objects

Note that the Schema Reference in this help file contains only a sample of the available business objects. See the Business Object Reference Library on the Support Zone at www.syspro.com for the latest information.

Business Object Name | Description | Root element | XmlParameters XSD Schema / XML Instance | XmlIn XSD Schema / XML Instance
ARSSCS | Update Customer | <SetupArCustomer> | ARSSCS.XSD ARSSCS.XML | ARSSCSDOC.XSD ARSSCSDOC.XML
BOMSMC | Update BOM Machine | <SetupBomMachine> | BOMSMC.XSD BOMSMC.XML | BOMSMCDOC.XSD BOMSMCDOC.XML
BOMSRO | Update BOM Routing | <SetupBomRouting> | BOMSRO.XSD BOMSRO.XML | BOMSRODOC.XSD BOMSRODOC.XML
BOMSSN | Update BOM Narration | <SetupBomNarration | {none} | BOMSSN.XSD BOMSSN.XML
BOMSST | Update BOM Structure | <SetupBomStructure> | BOMSST.XSD BOMSST.XML | BOMSSTDOC.XSD BOMSSTDOC.XML
BOMSWC | Update BOM Work Center | <SetupBomWorkCentre> | BOMSWC.XSD BOMSWC.XML | BOMSWCDOC.XSD BOMSWCDOC.XML
COMPAS | Update Operator Password | <SetupPassword> | {none} | COMPAS.XSD COMPAS.XML
COMSFM | Update a Custom Form field for a key field | <SetupCustomForm> | COMSFM.XSD COMSFM.XML | COMSFMDOC.XSD COMSFMDOC.XML
INVSPR | Update Price for a stock code | <SetupInvPrice> | INVSPR.XSD INVSPR.XML | INVSPRDOC.XSD INVSPRDOC.XML
INVSSR | Update a Serial Number for a stock code | <SetupInvSerialHead> | INVSSR.XSD INVSSR.XML | INVSSRDOC.XSD INVSSRDOC.XML
INVSST | Update Stock Code | <SetupInvMaster> | INVSST.XSD INVSST.XML | INVSSTDOC.XSD INVSSTDOC.XML
INVSWS | Update Warehouse for a stock code | <SetupInvWarehouse> | INVSWS.XSD INVSWS.XML | INVSWSDOC.XSD INVSWSDOC.XML
QOTSNS | Update Quotation Non-stocked items | <SetupQotNonStock> | QOTSNS.XSD QOTSNS.XML | QOTSNSDOC.XSD QOTSNSDOC.XML
QOTSRO | Update Routing for Estimates for non-stocked items | <SetupQotRouting> | QOTSRO.XSD QOTSRO.XML | QOTSRODOC.XSD QOTSRODOC.XML
QOTSST | Update Component for Estimates for non-stocked items | <SetupQotStructure> | QOTSST.XSD QOTSST.XML | QOTSSTDOC.XSD QOTSSTDOC.XML

Summary of available Setup Business Objects

This section gives a brief summary of the use of each setup business object.

ARSSCS - A/R Customer Setup

Use this business object to update customer details.

BOMSMC - BOM Machine Setup

Use this business object to update a BOM Machine.

BOMSRO - BOM Routing Setup

Use this business object to update a BOM Routing - list of operations - for a parent part.

BOMSSN - BOM Narration Setup

Use this business object to update narrations. The following narration types can be updated:

- Job narration

- WIP material narration

- WIP operation narration

- BOM structure narration

- BOM operation narration

- Estimate structure narration

See the schema BOMSSN.XSD for the available narration types and how to define the key fields.

BOMSST - BOM Structure Setup

Use this business object to update BOM structure details. This allows a parent / component structure to be changed.

BOMSWC - BOM Work Center Setup

Use this business object to update a BOM Work Center.

COMPAS - Change Operator Password

Use this business object to change the operator password for the current logged in operator. This can be used to keep SYSPRO e.net solutions passwords in-sync with other 3rd party system passwords. Note that there is only a Setup.Update method call to this business object. You cannot use the Setup.Add or Setup.Delete method.

COMSFM - Custom Form Setup

Use this business object to update a Custom Form field against an existing key field.

INVSPR - Inventory Price Code Setup

Use this business object to update price code details against a stock code.

INVSSR - Inventory Serial Number Setup

Use this business object to update a serial number against a stock code.

INVSST - Inventory Stock Code Setup

Use this business object to update stock code details.

INVSWS - Inventory Warehouse Setup

Use this business object to update warehouse details against a stock code. Note that the unit cost cannot be changed using this function. You must use an Inventory cost change function to change a unit cost against a warehouse.

QOTSNS - Quotation Non-stocked Maintenance Setup

Use this business object to update non-stocked codes that will be used for the non-stocked items within quotations.

QOTSRO - Quotation Routing Setup

Use this business object to update routing information for Estimates of non-stocked items.

QOTSST - Quotation Component Setup

Use this business object to update component information for Estimates of non-stocked items.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic query returning a sales order

Dim Setup As New Encore.Setup()

Dim XmlOut As String

' Build an XML string to pass parameters

Dim XmlParameters As String

XmlParameters =

"<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<SetupArCustomer>" &_

"<Parameters>" &_

"<IgnoreWarnings>N</IgnoreWarnings>" &_

"<ApplyIfEntireDocumentValid>Y</ApplyIfEntireDocumentValid>" &_

"<ValidateOnly>N</ValidateOnly>" &_

"<DeletePassword/>" &_

"</Parameters>" &_

"</SetupArCustomer>"

' Build an XML string to update a customer name

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<SetupArCustomer>" &_

"<Item/>" &_

"<Key" &_

"<Customer>0000002</Customer>" &_

"</Key> &_

"<Name>Bikes and Blades - North</Name>" &_

"</Item>" &_

"</SetupArCustomer>"

Try

XmlOut = Setup.Update(UserId, "ARSSCS", XmlParameters, XmlIn)

Catch exc As Exception

Response.Write("Unable to run business object ARSSCS - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

BusinessObject (string)

This is the name of a SYSPRO Setup business object. Typically SYSPRO setup business objects start with a 3 character module code mnemonic and are followed by S and another two characters. For example the Customer Setup Business Object is called ARSSCS.

XmlParameters (string)

This is a well formed XML string providing parameters to the Update method. You can indicate that you only want to validate the items and you can indicate that only if all the validations succeed will any data be update.

XmlIn (string)

This is a well formed XML string providing the data to be updated. Only element values supplied will be updated.

Output parameters

ReturnCode (string)

This is a return status code.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, XML Output


Setup.Delete

The Setup.Delete method allows you to delete data in the SYSPRO data structures. There are a number of Setup business objects that accept an XML string passing the data to be deleted. Each business object is identified by a name - see the table below.

The session must have been created using the Utilities.Logon method.

Syntax summary

Use of this method

ReturnCode = Setup.Delete(UserId, BusinessObject, XmlParameters, XmlIn)

Where

UserId is the UserId returned from the Logon method.

BusinessObject is the name of a SYSPRO Setup business object - see below

XmlParameters is a well formed XML string providing details of the function to be performed

XmlIn is a well formed XML string providing the data to be deleted

ReturnCode returns the status of the method call

XML input string(s)

When using the Delete method you must pass two XML strings. The first is a set of XML parameters that the Delete method will use to determine what to do and how to handle error conditions and the second is an XML string containing the keys of the items to be deleted.

While the general format of these strings are common across all Delete business objects the actual contents and permitted XML elements may differ from object to object. For this reason a set of XML schemas (XSD files) are documented that describe the permitted parameters and elements for each business object.

XML input string format

The XML input strings must be well formed. They must conform to the XML standards such as each opening element must have a closing element. Special characters, such as <, > and &, are not valid and will cause an XML parsing exception. e.net business objects ignore the case of element names when parsing the XML. See the topic on Well Formed XML.

Each XmlIn string has a unique root XML element to avoid accidentally passing the wrong XML strings to the wrong business object. The root element is the word Setup followed by the Table name. For example to delete data from the ArCustomer table the root element is <SetupArCustomer>.

XML Output string format

An XML Output string is returned from the Setup.Delete method. The contents of this string contain XML data indicating success or failure of the data being deleted.

If the deletion failed then the XML string contains a list of errors where XML Element <ErrorDescription> is used to describe the type of error.

In addition there is a summary of the results of the Delete method indicating the number of items read from the XML string and the number of failures.

Example XmlOut

The following example XmlOut string is returned when the Setup.Delete method is used to attempt to delete three customers (ARSSCS business object) one of which does not exist.

<?xml version="1.0" encoding="Windows-1252" ?>

<SetupArCustomer Language="05"
 CssStyle="" DecFormat="1" DateFormat="01"
 Role="01">

<item>

<key>

<Customer>0000002</Customer>

</key>

<Customer>

<Value>0000002</Value>

<ErrorDescription>Key '0000002' not found on 'ArCustomer'</ErrorDescription>

</Customer>

</item>

<StatusOfItems>

<RecordsRead>3</RecordsRead>

<RecordsInvalid>1</RecordsInvalid>

</StatusOfItems>

</SetupArCustomer>

Notice that the XmlOut string can contain multiple messages. Each message is always in the form of:

<Key>

<Key-Column-Name>key-value</Key-Column-Name>

</Key>

<Item-Name>

<Value>value-passed-to-method</Value>

<ErrorDescription>error-message-text</ErrorDescription>

</Item-Name>

Table of Available Delete Business Objects

Note that the Schema Reference in this help file contains only a sample of the available business objects. See the Business Object Reference Library on the Support Zone at www.syspro.com for the latest information.

Business Object Name | Description | Root element | XmlParameters XSD Schema / XML Instance | XmlIn XSD Schema / XML Instance
ARSSCS | Delete Customer | <SetupArCustomer> | ARSSCS.XSD ARSSCS.XML | ARSSCSDOC.XSD ARSSCSDOC.XML
BOMSMC | Delete BOM Machine | <SetupBomMachine> | BOMSMC.XSD BOMSMC.XML | BOMSMCDOC.XSD BOMSMCDOC.XML
BOMSRO | Delete BOM Routing | <SetupBomRouting> | BOMSRO.XSD BOMSRO.XML | BOMSRODOC.XSD BOMSRODOC.XML
BOMSSN | Delete BOM Narrations | <SetupBomNarration> | {none} | BOMSSN.XSD BOMSSN.XML
BOMSST | Delete BOM Structure | <SetupBomStructure> | BOMSST.XSD BOMSST.XML | BOMSSTDOC.XSD BOMSSTDOC.XML
BOMSWC | Delete BOM Work Center | <SetupBomWorkCentre> | BOMSWC.XSD BOMSWC.XML | BOMSWCDOC.XSD BOMSWCDOC.XML
COMSFM | Delete a Custom Form field for a key field | <SetupCustomForm> | COMSFM.XSD COMSDM.XML | COMSFMDOC.XSD COMSDMDOC.XML
INVSPR | Delete Price for a stock code | <SetupInvPrice> | INVSPR.XSD INVSPR.XML | INVSPRDOC.XSD INVSPRDOC.XML
INVSSR | Delete Serial Number for a stock code | <SetupInvSerialHead> | INVSSR.XSD INVSSR.XML | INVSSRDOC.XSD INVSSRDOC.XML
INVSST | Delete Stock Code | <SetupInvMaster> | INVSST.XSD INVSST.XML | INVSSTDOC.XSD INVSSTDOC.XML
INVSWS | Delete Warehouse for a stock code | <SetupInvWarehouse> | INVSWS.XSD INVSWS.XML | INVSWSDOC.XSD INVSWSDOC.XML
QOTSNS | Delete Quotation Non-stocked codes | <SetupQotNonStock> | QOTSNS.XSD QOTSNS.XML | QOTSNSDOC.XSD QOTSNSDOC.XML
QOTSRO | Update Routing for Estimates for non-stocked items | <SetupQotRouting> | QOTSRO.XSD QOTSRO.XML | QOTSRODOC.XSD QOTSRODOC.XML
QOTSST | Delete Component for Estimates for non-stocked items | <SetupQotStructure> | QOTSST.XSD QOTSST.XML | QOTSSTDOC.XSD QOTSSTDOC.XML
Summary of available Setup Business Objects

This section gives a brief summary of the use of each setup business object.

ARSSCS - A/R Customer Setup

Use this business object to delete customers.

BOMSMC - BOM Machine Setup

Use this business object to delete a BOM Machine.

BOMSRO - BOM Routing Setup

Use this business object to delete a BOM Routing - list of operations - for a parent part.

BOMSSN - BOM Narration Setup

Use this business object to delete narrations. The following narration types can be deleted:

- Job narration

- WIP material narration

- WIP operation narration

- BOM structure narration

- BOM operation narration

- Estimate structure narration

See the schema BOMSSN.XSD for the available narration types and how to define the key fields.

BOMSST - BOM Structure Setup

Use this business object to delete BOM structures.

BOMSWC - BOM Work Center Setup

Use this business object to delete a BOM Work Center.

COMSFM - Custom Form Setup

Use this business object to delete a Custom Form field against an existing key field.

INVSPR - Inventory Price Code Setup

Use this business object to delete price codes against a stock code.

INVSSR - Inventory Serial Number Setup

Use this business object to delete a serial number against a stock code.

INVSST - Inventory Stock Code Setup

Use this business object to delete stock codes.

INVSWS - Inventory Warehouse Setup

Use this business object to delete warehouses against a stock code.

QOTSNS - Quotation Non-stocked Maintenance Setup

Use this business object to delete non-stocked codes that are used for non-stocked items within quotations.

QOTSRO - Quotation Routing Setup

Use this business object to delete routing information for Estimates of non-stocked items.

QOTSST - Quotation Component Setup

Use this business object to delete component information for Estimates of non-stocked items.

Sample ASP.NET code

' Logon and trap any exceptions

Dim UserId As String

Dim Obj As New Encore.Utilities()

Try

UserId = Obj.Logon("ADMIN", " ", "1", " ", 5, 0, 0, " ")

Catch exc As Exception

Response.Write("Exception - message:" & exc.Message)

Exit Sub

End Try

' Run generic query returning a sales order

Dim Setup As New Encore.Setup()

Dim XmlOut As String

' Build an XML string to pass parameters

Dim XmlParameters As String

XmlParameters =

"<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<SetupArCustomer>" &_

"<Parameters>" &_

"<IgnoreWarnings>N</IgnoreWarnings>" &_

"<ApplyIfEntireDocumentValid>Y</ApplyIfEntireDocumentValid>" &_

"<ValidateOnly>N</ValidateOnly>" &_

"<DeletePassword/>" &_

"</Parameters>" &_

"</SetupArCustomer>"

' Build an XML string to delete a customer

Dim XmlIn As String

XmlIn = "<?xml version=""1.0"" encoding=""Windows-1252""?>" &_

"<SetupArCustomer>" &_

"<Item/>" &_

"<Key" &_

"<Customer>0000002</Customer>" &_

"</Key> &_

"</Item>" &_

"</SetupArCustomer>"

Try

XmlOut = Setup.Delete(UserId, "ARSSCS", XmlParameters, XmlIn)

Catch exc As Exception

Response.Write("Unable to run business object ARSSCS - Exception:" & exc.Message)

Exit Sub

End Try

Response.Write(XmlOut)

Response.ContentType = "text/xml"

' Logoff and Cancel your current Session

Dim ReturnCode As Long

ReturnCode = Obj.Logoff(UserId)

Obj = Nothing

Input parameters

UserId (string)

The UserId must be a valid string returned using the Utilities.Logon method. This ensures that the correct session is being referenced.

BusinessObject (string)

This is the name of a SYSPRO Setup business object. Typically SYSPRO setup business objects start with a 3 character module code mnemonic and are followed by S and another two characters. For example the Customer Setup Business Object is called ARSSCS.

XmlParameters (string)

This is a well formed XML string providing parameters for the Delete method.

XmlIn (string)

This is a well formed XML string providing the keys of the items to be deleted.

Output parameters

ReturnCode (string)

This is a return status code.

Requirements

Version: e.net 1.0 and later

See also

UserId, Error Handling, XML Schemas, Utilities.Logon, business object, Well Formed XML, XML Output


COMQEX

e.net SDK

Object Model Reference

COMQEX - Executive View Query

The purpose of this business object is to return an executive level view of the financial health of your business.

Data returned can include: Inventory Valuation, A/R and A/P balances, Bank balances, Invoices sales, Sales Orders taken, changed or cancelled in the recent past, outstanding Purchase orders, outstanding Sales orders and Work in Progress values.

Notes on the Inventory Values Returned

The value returned for each warehouse by this business object may not be exactly the same value shown by the Inventory Valuation Query business object (INVQSL) nor the SYSPRO Inventory Valuation Report nor the SYSPRO Inventory At a Glance values.

This discrepancy may occur when you have multiple bins defined against a warehouse as the rounding may differ slightly between this business object and the other programs mentioned.

The reason for the difference is that the Executive View is a high-level view of the financial health of the company and must be as quick as possible - whereas the other programs are much more detailed and must also balance to each other.

See also

Business Object, Query.Query, COMQEX.XSD, COMQEX.XML


REPQRY

e.net SDK

Object Model Reference

REPQRY - Report Writer Query

The main purpose of this business object is to run a pre-defined report configured using the SYSPRO Report Writer system. In addition the object can return any run-time prompts defined against a report and it can also return a list of reports that support XML output.

Running a Report

To run a report simply place the report code in the <Report> element in the input XML. The following example shows how to run the predefined report called INVP25 using the default run-time settings:

<Query>

<Key>

<Report>INVP25</Report>

</Key>

</Query>

The report to be run must be configured for XML output (use the Report Options and select XML). The following topics provide additional information and remarks about running a report from this Business Object.

Transforming for web viewing

The XML Wizard can be used to configure the report to be transformed for web viewing. If the report is not transformed for web viewing then simple (raw) XML will be output. This means that the XML is in a simple format with each field to be output being defined as an element and it's value. For example if the StockCode column is being output from the InvMaster table then the element will look as follows:

<StockCode>B100</StockCode>

In addition there is a simple structure to the XML. There is a root element and within this a number of group level elements such as <ReportHeading> and <ReportDetail> the names of the root element and group level elements can be configured using the XML Report Wizard. If you want to change the structure of the XML then you require to develop an XSL transformation for your own application.

If the report is transformed for web viewing then the format of the XML is quite different. The format of the XML is designed to be processed by an XSL transformation called RWREPORT.XSL (found in the SYSPRO samples folder). In addition a <Style> element in the XML defines the name of a stylesheet (CSS) to be used by the XSL to render the theme. This defines each objects attributes - font, size, color etc.

If the report is transformed for web viewing then the XSL file (RWREPORT.XSL) and theme files (RW*.CSS RW*.JPG RW*.GIF depending on the theme selected) must be available on the client system. These are all found in the SYSPRO samples folder.

By providing the above mentioned files and refreshing the returned XML inside a browser object - this will cause the report to be rendered correctly.

Providing run-time parameters

When running a report you may wish to pass run-time parameters to modify the processing of the report. The XML supports the following run-time-parameters:

- Report sequence

- Initial values for run-time prompts (including check boxes)

- Summary/Detail option

See the schema REPQRY.XSD for a complete definition of the valid run-time parameters.

Limitations in the REPQRY business object

Detail/Summary reports

The report can be defined as being Detail or Summary. In addition you may override this setting in the XML at run-time. In either case if a summary report is selected and the XML wizard is defined as having a detail zoom then the zoom facility is not available from the Business Object. In this case the details will simply not be output.

Automatic processing after report completion

A report can be configured to automatically trigger another report after the first report has completed. This facility is not available from the Business Object. You can run the second report from your application if required.

In addition you can configure a report to automatically trigger the Sequential to Index converter utility after a report has completed. This facility is not available from the Business Object.

Any Publish functionality is not available when running a report using the Business Object. It is assumed that your application wants the XML directly.

Retrieving Run-time Parameters for a Report

In addition to being able to run a report the REPQRY business object also allows you to retrieve information about any run-time parameters available against the report - this includes any report sequences, run-time variables and their types and defaults.

This function could be used by an application to find the parameters and then request them from the operator and then pass them to the run a report function.

To retrieve information about the run-time parameters supply a <Retrieve> element with a value of Y. See the following example XML:

<Query>

<Key>

<Report>INVP25</Report>

</Key>

<Option>

<Retrieve>Y</Retrieve>

</Option>

</Query>

Read a List of XML Reports

The REQPRY business object also provides the ability to return a list of reports configured for XML output. The format of the output XML is consistent with the generic browse Query.Browse method.

To specify that you want to return a list of reports specify {all} in the <Report> element. See the following example XML:

<Query>

<Key>

<Report>{all}</Report>

</Key>

</Query>

See also

Business Object, Query.Query, REPQRY.XSD, REPQRY.XML


SYSPRO Overview

Traditionally developers working with SYSPRO 6.1 (or earlier versions such as SYSPRO 6.0, Encore 5.1 and Encore 5.0) need to work with Net Express and the Dialog System to develop their applications. You need to use the standard SYSPRO copybooks for the record layouts (tables and columns) and you use the standard routines to handle file access etc.

Programming at this level gives tremendous power to a developer, however it can be daunting and time consuming to learn this technology. The SYSPRO SDK documentation assists the developer in learning to use these functions and includes sample code to demonstrate various techniques.

If you need to develop applications in other languages such as C#, VB.NET, ASP.NET, VB and ASP 3.0 or other COM enabled languages and need access to various SYSPRO functions then you should see the e.net overview topic.

What is the SYSPRO SDK?

The SYSPRO SDK is aimed at developers who wish to write new programs and systems or to customize existing programs to run from SYSPRO. It is primarily aimed at developers using Net Express and the Dialog System.

The SYSPRO SDK includes sample source code, copybooks, file handlers, and compiler support files.

After reading this introduction it is recommended that you read Setting up a development environment.

If you are using the Screen Customization Kit then you should read the Screen Customization Kit introduction and the associated topics.

Where should I start?

There's something for everyone depending on your knowledge and experience. Some good places to start are:

  • Setting up a development environment takes you through installing the SYSPRO SDK. If you are developing SYSPRO programs then you should do this first to install the sample source code and compiler support files.

  • Basic sample program is a walk through of a sample SYSPRO application and how it is constructed. Useful if you haven't worked on SYSPRO 6.1 or SYSPRO 6.0 programs before.

  • Functions by name and Functions by type are the SYSPRO source code function references. These are a complete explanations of the functions available in PROBEGIN.PRO. A knowledge of these is important for new and existing developers working with SYSPRO.

  • Dialog functions by name and Dialog functions by type are the screenset function reference. This explains all the functions available from a screenset using the standard SYSPRO copybooks.

  • File status codes is a reference of the most common Net Express run-time codes returned by the file handling functions.

  • SQL Server tuning and Transaction Processing topics cover how to get the best from SYSPRO running on SQL Server.

  • The Source code samples provide demonstrations of various programming techniques for SYSPRO developers.

  • If you are having deployment problems for your SYSPRO custom programs, perhaps only on certain platforms, then see the Deploying Custom Programs topic.

Copyright Notice

SYSPRO is protected by international copyright.

See also

Setting up a development environment, Screen Customization Kit introduction, Basic sample program, Functions by name, Functions by type, Dialog functions by name, Dialog functions by type, File status codes, SQL Server tuning, Transaction Processing, Source code samples, e.net overview, Deploying Custom Programs


What's new in SYSPRO 6.1 SP1

e.net SDK

XML

What's new about SYSPRO 6.1 SP1

SYSPRO 6.1 SP1 is mainly a consolidated set of fixes and a few minor updates over SYSPRO 6.1.

In addition there are a minor set of database changes. The tax rate has been increased to have 3 decimals and each file that contains a tax rate has been changed.

For a complete and up-to-date list of features and changes see the Support Zone at www.syspro.com.

Information for developers

SYSPRO 6.1 was one of the most significant software releases that we have ever produced, therefore if you are new to SYSPRO 6.1 see the topic What's new in SYSPRO 6.1.

SYSPRO 6.1 SP1, on the other hand, is a minor update and apart from 11 tables that contain tax rates, the copybooks are the same. A simple recompile is all that is required for SYSPRO 6.1 SP1 development.

For more details about the database changes see the topic SYSPRO 6.1 SP1 Database Changes.

e.net solutions developers need not worry about changes to the SYSPRO database as the business objects seamlessly handle any changes to the SYSPRO database. The only exception to this is where you may have used one of the generic database access business objects - in which case you should review your code for possible changes.

Version upgraded from 6.1 to 6.1 SP1

The copybook STANDARD.WRK, that is included in all standard SYSPRO programs, has three fields that define the version, issue and service pack of SYSPRO. If required you can use these fields to develop generic logic that takes account of the version of software. These fields now have the following values:

01 SYSTEM-VERSION PIC X(3) VALUE "6.1".

* Current SYSPRO version

01 SYSTEM-ISSUE PIC X(3) VALUE "001".

* Current SYSPRO issue number

* (Must say minimum of '001')

01 SYSTEM-SP PIC X VALUE "1".

* Current SYSPRO service pack

* (Must say 'value spaces'

* when there is no service pack)

From the above commented source code you should notice that the version is '6.1' the issue is '001' and the service pack is '1'.

Also note that from now onwards it is our intention not to use the field 'SYSTEM-ISSUE'. The 'Issues' of the product were product updates and we will no longer be using this style of product version naming - we will just use version and service pack.

Number of decimals in tax rate

As mentioned above the only database changes for SYSPRO 6.1 SP1 are that tax rates now contain 3 decimal places (previously 2 decimal places). Note that there is a company setup option named IM0-TAX-DECS (in linkage) that stores the number of decimals to be used when showing, prompting and printing the tax rates.

Similarly a field defined per tax code named ADMTAX-TAX-DECS is available. If this has a value of zero then you should use the value defined at the company level.

Due to the above change in tax rate decimals the only other change to SYSPRO 6.1 SP1 copybooks was in the tax calculation routines defined in TAX.WRK and TAX.PRO.

Notice of Future Deprecation

Print Offsets

Note that from SYSPRO 7 the Print Offset logic that can be used to managed long print lines will be removed. This logic is still fully supported in SYSPRO 6.1.

See also

What's new in SYSPRO 6.1, SYSPRO 6.1 SP1 Database Changes


What's new about SYSPRO 6.1

As always each new issue of SYSPRO software has many new features and SYSPRO 6.1 is no exception. In fact from a development perspective this is probably the largest ever single change. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

If you want information about SYSPRO 6.1 SP1 see the topic about 6.1 SP1.

Several of the features in SYSPRO 6.0 Issue 010 SP2 were only released with one of the monthly enhancement ports and therefore did not appear on the initial SP2 CD. SYSPRO 6.1 is a consolidation of all the SP2 features and bug fixes. In addition 6 new modules and a large number of other features have also been released - these include:

New modules

Warehouse management

Inventory Optimization

Workflow Services

Workflow Services Professional

Executive Dashboards

Process Modeling

Greater use of enhanced user-interface elements throughout the product

Enhanced user-interface capability and customization

Real-time General Ledger and re-engineered GL integration

Cash Flow Forecasting

Revised Assets Register System

Actual Cost Tracking

Manufacturing Unit of Measure

Stores Issues from Requisitions

Reserving Quantities in Sales Orders

Enhanced Role Management

SYSPRO Analytics Enhancements

SRS Document Printing enhancements and archiving

Automated batch processes

Information for developers

SYSPRO 6.1 is one of the most significant software releases that we have ever produced and therefore there are also a number of important changes to the SYSPRO database structure. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.1 Database Changes. In particular note that the General Ledger Integration and Assets Register have significant database changes.

Due to the file changes mentioned above and other architectural changes you must recompile all Net Express source code programs specifically for SYSPRO 6.1 using the latest copybooks from the SYSPRO 6.1 SDK. This ZIP file is available from the SYSPRO Support Zone.

Note that the SYSPRO 6.1 data conversion wizard can only be used to convert SYSPRO 6.0 Issue 010 SP2 format companies to SYSPRO 6.1.

e.net solutions developers need not worry about changes to the SYSPRO database as the business objects seamlessly handle any changes to the SYSPRO database. The only exception to this is where you may have used one of the generic database access business objects - in which case you should review your code for possible changes.

Important SYSPRO 6.1 information

The following topics describe the most important information that SYSPRO 6.1 developers should be aware of before starting any development on this new version.

Setting up a development environment

As we are using Net Express 5.1 for the first time you should read the topic Setting up a Development Environment for SYSPRO 6.1 rather than rely on previous experience.

We have used some new compiler directives and you will notice that we are using a new NX variable value (NX=5.1) for our command line batch compiler - COMPILE. The directives are covered in more detail later in this topic.

TOOLKIT.INI and SRCCPB=

When you use the data dictionary utilities to import your own record layouts or export various copybooks and other files we use entries in the TOOLKIT.INI file (located in the SYSPRO base folder). From SYSPRO 6.1 there is a new SRCCPB= entry that should be used to point to your copybook folder. Previously we assumed that the sub folder named COPY60 resided beneath the SOURCE folder. When setting up your development environment remember to review this entry in the supplied TOOLKIT.INI file to ensure the value is appropriate.

Net Express 5.1 run time

Up to now we have shipped the Net Express run time components in the SYSPRO base folder. From SYSPRO 6.1 the Net Express 5.1 run time system is installed as a separate application and therefore it's components (EXE, DLL, LBR etc.) have been removed from the SYSPRO base folder.

It's important that you do not have any components from the older versions of Net Express in the SYSPRO base folder. If you leave older run time components in your base folder you can have problems compiling from Net Express and/or running and debugging SYSPRO.

Customizable Toolbar - New BASE\UI folder

Until now our toolbars have not been customizable by an end user as the toolbar design was compiled into a toolbar user control program. From SYSPRO 6.1 many of our applications now use the Codejock toolbar that is customizable by the end user. The Toolbar definitions are stored in a new folder below BASE called UI. The toolbar definition files have an XCB extension.

Details of how to create these customizable toolbars are beyond the scope of this document (see more information on the Support Zone).

However, in summary, we still have a small toolbar user control program that (in effect) points to an appropriate XCB file located in the BASE\UI folder. For example the Inventory Query toolbar program (INVPENTB) points to the toolbar definition file (INVPENTB.XCB).

We have provided a Toolbar designer program that is used to edit the XCB format files as part of the Software Development Kit. This program is part of the Codejock development system and is subject to their copyright.

To use the Toolbar designer locate and run the executable:

C:\rnd60\designers\TOOLBAR\SysproToolbar.exe

It is recommended that you create a windows shortcut to this executable.

Use File > Open and navigate to c:\rnd60\base\ui and select one of the toolbars (e.g. INVPENTB.XCB).

The previous style toolbars are still fully supported and many standard programs still use them for SYSPRO 6.1. However it is our intention to replace most (if not all) of our standard toolbars in future versions of SYSPRO.

Customizable Listviews - New BASE\UI folder

We have different methods of developing listviews, some retained for legacy purposes, however all of them require a programmer to develop a source code program that contains parameters relating to the listview and it's columns.

Whilst this is flexible and powerful we have decided to provide a more visual method of editing and designing listviews for SYSPRO 6.1.

Therefore for the first time we have provided a listview designer application. This exposes all the capabilities of the very latest listview technology used by SYSPRO 6.1 and it is recommended that new listviews are developed using this technology. You can migrate your older listviews to these new ones over time.

The visual listview designer stores it's listview definitions as XML files in the new folder BASE\UI. The same location as the new customizable toolbars.

Details of how to create these new listview XML files are beyond the scope of this document (see more information on the Support Zone). However, in summary, we still have a small listview user control program that (in effect) points to a appropriate XML file located in the BASE\UI folder. For example the Inventory Query listview program (INVPENLV) points to the listview definition file (INVPENLV.XML).

We have provided a Listview designer program that is used to edit these XML format files as part of the Software Development Kit.

To use the Listview designer locate and run the executable:

C:\rnd60\designers\LISTVIEW\SysproListview.exe

It is recommended that you create a windows shortcut to this executable.

Use File > Open and navigate to c:\rnd60\base\ui and select one of the toolbars (e.g. INVPENLV.XML).

The previous style listviews are still fully supported and many standard programs still use them for SYSPRO 6.1. However it is our intention to replace most (if not all) of our standard listviews if future versions of SYSPRO.

Developer Guides

As there is so much new technology since SYSPRO 6.1 we have authored and published developer guides that are aimed at developers using Net Express and SYSPRO to help them get up to speed with the new user interface features.

The developer guides include a summary of all user interface technologies and functions that are new for SYSPRO 6.1. In addition there is a separate document for each type of user interface element.

If you are new to SYSPRO or have only limited experience with SYSPRO 6.0 Issue 010 SP2 user interface development then there are a set of SYSPRO 6.0 Issue 010 SP2 training guides that provide an introduction to each feature and a step by step guide to get started with their development. These guides make extensive reference to source code supplied as part of the SYSPRO 6.1 Software Development Kit.

These guides are available on the Support Zone (see the Developers section).

Due to the extensive user interface documentation available on the Support Zone the 'User Controls' section of this SDK documentation has been removed as it was very limited and is now obsolete for SYSPRO 6.1.

Note

If you receive an error when compiling a listview that contains the message:

Please run APPCNV on your BINSRC folder for this application

Then please read the document entitled '6.1 Developer changes' on the developers section of the Support Zone.

Updated compiler directive files for SYSPRO 6.1

For the first time in many versions of SYSPRO we have updated our default compiler directive files for SYSPRO 6.1. It is critical that you use these new compiler directive files when compiling your programs.

Compiling using COMPILE.BAT

When you compile from the command line using COMPILE.BAT it will automatically use the latest compiler directives based on the command line options you supply.

For example if you compile the sample program SDK001 for animation using:

COMPILE /A SDK001

Then the directive file COMPANIM.DIR is used.

The directive files shipped as part of the SYSPRO 6.1 Software Development Kit contain the appropriate directives and there is nothing else for you to do.

Compiling from Net Express

When you compile your source code directly from within Net Express it will use the directives specified depending on whether you are running from within a Net Express project or not.

When running from outside a project you must set the Compile Single File settings (Options > Compile Single File) to use the SYSPRO directives file. It is suggested that you use the following string:

%FILENAME NOGNT WB3 WB CSI ANIM EDITOR(MF2) ENSUITE(3) INT(c:\rnd60\prg\%BASENAME.INT) DIR(c:\rnd60\source\companim.dir);

Note that you should replace each occurrence of the string 'c:\rnd60' with the root path of the location of your source code.

This string indicates that the location of generated animator support IDY files will be stored in the 'prg' folder, that the compiled file name generated will be your program name followed by '.INT' in the 'prg' folder and that the compiler directives file COMPANIM.DIR will be used from the 'source' folder.

The last part that says: DIR(c:\rnd60\source\companim.dir) points directly to the standard SYSPRO directives file used when compiling for animation from the command line (as mentioned earlier).

When running from within a project you set your directives against the project properties (Project > Properties). The dialog contains a 'project directives' value that can be set to the same string as listed above.

For your information there are several directives that have changed or been added - these include:

QUAL

When compiling all SYSPRO 6.1 programs we now use the QUAL directive indicating that 'Qualified data names' can be defined. This means that it is quite permissible to create two '01' level records each having the same subordinate field.

For example:

01 stock-record.

03 stock-code pic x(30).

01 order-record.

03 stock-code pic x(30).

Note that the field 'stock-code' exists in both group records. Therefore to identify which 'stock-code' field you want to access you must suffix the field name with the phrase 'OF' and the record name.

For example to test whether the first instance of stock-code is spaces you can use:

IF STOCK-CODE OF STOCK-RECORD = SPACES

Any program that currently includes the directive

$SET QUAL

in the source code can be changed (if required) to remove this line.

REENTRANT"2"

When compiling all SYSPRO 6.1 programs we now use the REENTRANT"2" directive indicating that when running SYSPRO programs in a multi-threaded environment that each instance of data defined in Working Storage is to be kept separate.

Until now we insisted that programs that could be run in an e.net environment had the following directives defined in their source code:

$set REENTRANT(2)

$set CONSTANT REENTRANT-DIRECTIVE(2)

This is no longer required and both directives in the source code can be removed.

In addition the validation code in PROBEGIN.PRO that attempts to test that these directives have been set has been removed.

As this directive is used as standard the 'enet03' diagnostic is no longer required/supported as this was used to test whether the REENTRANT-DIRECTIVE constant was set.

SQL Server locking and other differences from ISAM

There is a new article explaining the differences between SQL Server and ISAM environments when using the common file logic functions. This includes an enhancement to the way that the READ-LOCK and READ-WAIT functions work in a SQL Server environment. See the topic SQL Server and ISAM Differences.

Direct read via an alternate index has been removed for a SQL based file

When using the generic file handling logic that supports both ISAM and SQL Server based systems there is a SQL file handler (stored in BASE\FH) that handles the database access.

These file handlers attempt to completely duplicate the ISAM logic provided by the Net Express run time system on SQL Server. However there are some differences. See the topic SQL Server and ISAM Differences.

The SQL file handlers support START and READ NEXT/READ PREVIOUS logic. However they have never supported a direct READ via an alternate index. Unfortunately there was a function in each file handler logic copybook (CFL) that appeared to support this feature. Whilst it did work in an ISAM environment it did not provide the correct database access when running on SQL Server. This situation had existed since we first produced a SQL Server version of SYSPRO and is not a new issue.

As this has caused some problems when developers have inadvertently used these functions (expecting them to work) we have decided to remove the direct READ via an alternate key for record layouts defined with a MAC extension.

Note that a direct READ via an alternate index is still supported on files that always stay as ISAM (e.g. MAI and MAT record layouts).

Net Express 5.1 and SQL Server datetime columns

Database access performed using the generic ISAM functions (such as XXXXXX-READ etc.) or from the SQL Server Tuning code has not changed significantly for SYSPRO 6.1.

However if you have coded your own database access using embedded SQL commands (EXEC SQL) then you should be aware that Net Express 5.1 returns datetime columns differently when using dynamic SQL than it did with Net Express 4.0.

In Net Express 4.0 datatime columns were returned as edited alphanumeric data. However from Net Express 5.1 datetime columns are returned with the following structure:

****************************************************************

** Date format for Net Express 5.1 onwards TIMESTAMP-RECORD **

****************************************************************

01 DATE-FORMAT.

03 DATE-YEAR PIC S9(4) COMP-5.

03 DATE-MONTH PIC S9(4) COMP-5.

03 DATE-DAY PIC S9(4) COMP-5.

03 DATE-HOUR PIC S9(4) COMP-5.

03 DATE-MIN PIC S9(4) COMP-5.

03 DATE-SEC PIC S9(4) COMP-5.

03 DATE-FRAC PIC S9(9) COMP-5.

The new SQLTYPE values returned are defined by the following constants (see SQLOPCOD.WRK):

78 DATATYPE-DATETIME2 VALUE 394. *> Net Express 5.1+

78 DATATYPE-DATETIME2-NULL VALUE 395. *> Net Express 5.1+

Net Express 5.1 and SQL Server variable length Unicode (nvarchar) columns

Database access performed using the generic ISAM functions (such as XXXXXX-READ etc.) or from the SQL Server Tuning code has not changed significantly for SYSPRO 6.1.

However if you have coded your own database access using embedded SQL commands (EXEC SQL) then you should be aware that Net Express 5.1 WrapPack 4 returns variable length Unicode (nvarchar) columns differently when using dynamic SQL than it did with prior versions of Net Express.

Net Express 5.1 WrapPack 4

SYSPRO 6.1 was initially released using Net Express 5.1 WrapPack 3 and therefore the issue mentioned in this topic was not relevant. However later versions (such as SYSPRO 6.1 SP1 onwards) will use later Wrap packs.

We have also had the situation where a SYSPRO site has a later Net Express 5.1 WrapPack installed due to other (non-SYSPRO) software being installed. This site then found that nvarchar data was not returned as expected.

As you cannot easily determine which Net Express WrapPack is installed it's difficult to know in which format nvarchar information is returned. To help with this issue we have setup an 'external' field that you can include in your code to test for the different formats. Remember this is only required it you directly code SQL statements in your program using the EXEC SQL syntax. The external field is:

01 EXT-IMPSQL-FMT-NVARCHAR PIC X IS EXTERNAL.

* Format returned by nvarchar

* A - Unicode - Prior to NE 5.1 WrapPack 4

* B - structured - From NE 5.1 WrapPack 4

When fetching nvarchar columns (for example from INFORMATION_SCHEMA.TABLES) the data will now be returned in the following structure:

******************************************************************

** Net Express 5.1 WrapPack 4 onwards nvarchar format strings **

******************************************************************

01 UNICODE-STRING.

03 UNICODE-STRING-LEN PIC S9(4) COMP-5.

03 UNICODE-STRING-CHR PIC N(300).

The following code fragment uses the nvarchar format flag and converts the Unicode string to ASCII:

01 TEMP-STRING PIC X(602).

01 ASCII-STRING PIC X(300).

*****************************************************************

** Routine to translate Unicode string to ASCII string **

** Takes account of flag set in IMPSQL **

** Input : UNICODE-STRING Unicode string **

** Output : ASCII-STRING ASCII string - space term **

*****************************************************************

MOVE-UNICODE-TO-ASCII.

if ext-impsql-fmt-nvarchar = "B" *> Structured format

move unicode-string-chr to temp-string

move spaces to ascii-string

move function display-of(temp-string)

to ascii-string(1:unicode-string-len)

else

move function display-of(unicode-string) to ascii-string

end-if.

Debugging on Unix

From SYSPRO 6.1 we use Server Express 5.1 for Unix deployments. This is much more compatible with Net Express 5.1 than previous versions of SYSPRO 6.0 development.

In fact you can now develop programs and compile them to intermediate code (.INT files) and transfer them to Unix systems using a binary transfer and they will work. Assuming they make no specific Windows assumptions they should work without requiring a recompile.

See the article called Debugging on Unix to assist with developing and debugging for a Unix environment.

Context Help is now Obsolete

As the Windows .HLP file format is obsolete from Windows Vista onwards SYSPRO have removed any context help for SYSPRO 6.1. The topic Creating Context Sensitive Help has been removed in this version of the SDK.

The context help is the help available by clicking on the small question mark icon at the top right of the Window previously available in our setup programs.

We have retained the copybooks QUESICON.WRK and QUESICON.PRO for a short period to give ourselves chance to remove the logic from the screenset that calls the previous context help user controls (??????QS). However these copybooks will be removed in future versions of the Software Development Kit.

Additional SYSPRO 6.1 developer features

The following topics describe additional information that developers working with SYSPRO 6.1 may find useful.

Version upgraded from 6.0 to 6.1

As this is such a significant upgrade to SYSPRO we decided to increment the system version to 6.1.

The copybook STANDARD.WRK, that is included in all standard SYSPRO programs, has three fields that define the version, issue and service pack of SYSPRO. If required you can use these fields to develop generic logic that takes account of the version of software. These fields now have the following values:

01 SYSTEM-VERSION PIC X(3) VALUE "6.1".

* Current SYSPRO version

01 SYSTEM-ISSUE PIC X(3) VALUE "001".

* Current SYSPRO issue number

* (Must say minimum of '001')

01 SYSTEM-SP PIC X VALUE SPACES.

* Current SYSPRO service pack

* (Must say 'value spaces'

* when there is no service pack)

From the above commented source code you should notice that the version is '6.1' the issue is '001' and the service pack is blank.

Data Dictionary Validation Utility

There is a new Data Dictionary Validation utility provided with SYSPRO 6.1.

This is designed to make it much easier for developers to verify that their new record layouts or changes to existing ones conform to the conventions and best practices used by SYSPRO development.

Some of the Data Dictionary limits have been increased for SYSPRO 6.1. See the list below (previous limits in brackets).

- Maximum primary key length is 200 characters (was 99)

- Maximum parts to an alternate key is 20 fields (was 8)

- Maximum alphanumeric field length is 3000 characters (was 1000)

Note that if you make use of the Data Dictionary Export function that there is a new 'Table and column filter' that will be used when exporting TABLE.SQL and COLUMN.SQL. This topic has been revised to explain how best to use this filter.

New modules use shared inventory id

The new Warehouse Management and Quality Management modules store their data using the shared inventory id defined against each company.

The topic Shared Inventory Files contains a table listing all modules (and files) that use the shared inventory id.

New Task Dialog user interface element

A new type of messaging user interface element called a Task Dialog has been introduced in SYSPRO 6.1. A Task Dialog is a more sophisticated type of message box.

Use the new INVOKE-TASK-DIALOG function from your Net Express program to show a task dialog.

The message box test harness program (SDKMSG) has been enhanced to demonstrate most of the task dialog features. See the example screenshot taken from the output of this test harness.

Note that when you invoke message boxes, either using the Dialog System or PERFORM INVOKE-MESSAGE-BOX from a Net Express program, these will be automatically converted to a task dialog on-the-fly. Although they may not be as effective as if you had programmed then specifically for the task dialog.

Also note that you should only use regular text or a line feed (x"0a") formatting character as text in a message box or task dialog. Other characters may cause spurious characters or unexpected results to be shown. For example a Tab character could appear as a tiny square.

Text shown in the Task Dialog will be translated - note that a maximum of 600 characters of text can be translated using the standard Language Translation logic. Take care when describing more that 600 characters of text.

Message box enhancement

Message boxes (and task dialogs) support the ability to have a check box saying 'Do not show this message again' (or similar).

In the past the PERFORM INVOKE-MESSAGE-BOX function allowed you to configure that you required this check box. In addition you had to supply a program name and message box code, against which the saved preference was saved.

However there was no easy way of resetting the checkbox to force the message box to be shown again.

There is a new function called INVOKE-MESSAGE-BOX-RESET that can be used to reset one or more of these saved preferences for both message boxes and task dialogs.

The message box test harness program (SDKMSG) demonstrates the use of this function.

Also note that an operator can now reset all their message box and task dialog warnings using the Personalize > Messages > Reset all Task Dialog Warnings button.

New functions to create folders

There are two new functions called CREATE-DIRECTORY-ON-CLIENT and CREATE-DIRECTORY-ON-SERVER that can be used to create subfolders below existing folders.

Similarly you can create folders on the client and server using dialog callouts S-OSMKDR and S-OSMKDRS respectively.

SQL optimization code support has been enhanced

For SYSPRO 6.1 the number of tables, columns, sequences, parameters etc. has been enhanced when using the SQL Server Tuning Code. The new limits in SYSPRO 6.1 are shown below (SP2 limits in brackets):

- 42 tables in a single SELECT (was 11)

- 300 columns can be returned in a single SELECT (was 200)

- 20 columns can be specified in an ORDER BY clause (was 10)

- 30 parameters can be defined per condition using %1 to %30 (was 20)

- Each parameter can be up to 100 alphanumeric characters (was 40)

- Joins up to 1000 characters can be defined per sub-table (was 215 unless you used a special 78 level)

- Each fetch returns the first 100 alphanumeric characters of each column automatically (was 40)

- Each fetch returns a null indicator per column (not previously available)

- Table names up to 30 characters are supported (was 18) - standard SYSPRO tables are still a max of 18

- Column names up to 30 characters are supported (was 18) - standard SYSPRO columns are still a max of 18

- Prefixes to a SELECT, such as TOP 100, can now be up to 100 characters (was 30)

- SQL-EXECUTE-COMMAND can issue SQL statements up to 15,000 characters (was 3000)

Note that the JOIN logic was enhanced during SP2 to allow you to specify up to 1000 characters by defining the constant:

78 SQL-WRK-LARGE-LINK VALUE 1.

This constant is no longer supported - you can just move up to 1000 character of join information to the field SQL-TAB-LK. If you previously used this 78 level you must replace the code from SP2 and simply use the new field.

Due to this and the other changes, the size of the copybook SQL.LNK is now 70,000 bytes.

All the SQL Server documentation has been revised to reference the new limits.

SQL Version now provided in linkage

The current version of SQL Server being used is now available to developers in the linkage field LINK-SQL-VRS. This field is populated when you login to SYSPRO and is therefore available to all SYSPRO programs.

This field can be used when you have specific SQL code that is only supported on specific versions or service packs of SQL Server. The field definition has been shown below. Note that the comments show some of the most common versions and service packs. Obviously the specific versions are subject to change in future as newer versions of SQL Server are released.

05 LINK-SQL-VRS.

07 LINK-SQL-VRS-MAJ PIC 9(2).

07 LINK-SQL-VRS-DT1 PIC X.

07 LINK-SQL-VRS-MID PIC 9(2).

07 LINK-SQL-VRS-DT2 PIC X.

07 LINK-SQL-VRS-MIN PIC 9(4).

* SQL Server full version

* For example

* '07.00.0699' - SQL 7.0 SP1

* '07.00.0842' - SQL 7.0 SP2

* '07.00.0961' - SQL 7.0 SP3

* '07.00.1063' - SQL 7.0 SP4

* '08.00.0194' - SQL 2000 RTM

* '08.00.0384' - SQL 2000 SP1

* '08.00.0534' - SQL 2000 SP2

* '08.00.0760' - SQL 2000 SP3

* '08.00.2039' - SQL 2000 SP4

* '09.00.1399' - SQL 2005 RTM

* '09.00.2047' - SQL 2005 SP1

* '09.00.3042' - SQL 2005 SP2

* '09.00.4035' - SQL 2005 SP3

* '10.00.1600' - SQL 2008 RTM

* '10.00.2531' - SQL 2008 SP1

New resource lock functions

Developers occasionally have the requirement that they need to be able to lock a resource that is not a table or row within a table. The Resource Locking functions provide a simple to use and standardized method of locking abstract resources without the problem of releasing the locks if something goes wrong and the program or computer crashes or the operator terminates the process unexpectedly.

This requirement is more common when developing using some of the later user interface technologies available in SYSPRO 6.1.

A good example is the Inventory Alternate Stock Code Maintenance program. In this case we may wish to lock the parent stock code during the maintenance of it's alternates - however locking the stock code is a serious thing to do in SYSPRO. In reality we just wish to prevent others from maintaining alternate stock codes for the same parent item at the same time.

The new functions include:

RESOURCE-LOCK-ADD

RESOURCE-LOCK-ADD-MSG

RESOURCE-LOCK-DELETE

RESOURCE-LOCK-TEST

RESOURCE-LOCK-TEST-MSG

SYSPRO now supports up to 9999 concurrent users

The field LINK-USER that stores the current user number has always been defined as a 4 digit numeric field. However until now only the values 001 - 999 were ever used. From SYSPRO 6.1 there can be up to 9999 concurrent users and therefore we have used the full 4 digits of the user field.

If you had previously used the field LINK-USER then ensure that you take account of the full 4 digits.

Temporary files allocated using the BUILD-TMPFIL and similar functions now use the 4 digit user number as part of the temporary file name rather than the 3 digits used previously and therefore the temporary file names are now 1 character longer than before.

Note that the user number assigned to each instance of SYSPRO is incremented each time an operator logs into SYSPRO and the field LINK-USER can have any value from 0001 - 9999 regardless of the maximum licensed users.

For example if you have a system licensed for 50 users then the first 50 users to login will be assigned user numbers 0001 through 0050. However as soon as someone logs out and someone then logs in user number 0051 upwards will be assigned. When user number 9999 is reached it will roll over to user number 0001 and start incrementing from this number - skipping any numbers where the current operator is still logged in.

Note that there is a field in the standard datablock named S-USER. This field is only defined as 3 digits and should no longer be used from SYSPRO 6.1 onwards.

New date functions

There are a number of new functions related to dates and date+time fields.

There is a new function IS-LEAP-YEAR that allows you to test whether a 4 digit year is a leap year or not. In addition it returns the number of days in February for the selected year.

There are also new functions that allow you to work with date+time fields. A date+time field defines two fields (a date and a time) that specifies a chronological moment. These functions allow you to determine the length of time between two date+time fields and to calculate future or past date+time values. The functions are:

CALC-DATETIME-AGE

CALC-DATETIME-NEW-DATE

CALC-DATETIME-NEW-DATE-NUM

Retrieving a list of companies

There are several new functions to allow you to retrieve a list of companies installed on your SYSPRO system.

In SYSPRO 6.1 and prior versions each company is identified by a company id. This is a single character in the range (A-Z, 0-9). However to determine which company id's are in use meant building and attempting to open each company control file (ADMCTL) one by one.

There are two new functions that perform this logic for you. The first just returns a list of company id's as a text string and the second returns a comma separated string of company id's.

GET-COMPANY-LIST-ALL

GET-COMPANY-LIST-ALL-COMMA

Similarly you may wish to retrieve a list of all company id's that have the same shared inventory id as the current company. These functions are named:

GET-COMPANY-LIST-INV

GET-COMPANY-LIST-INV-COMMA

Note that from SYSPRO 7.0 it is our intention to increase the length of the company id field and therefore you should consider allowing for more than a single character as the company id and using the comma separate version of the above functions.

Also it's worth considering the e.net business object COMQCO that can be used to retrieve a list of companies. It not only returns the company id for each company but also the company name, database access type and various other parameters.

Role security information

For the first time you can define a number of security settings and other configuration information by role.

In SYSPRO 6.0 you could define the following information against each operator:

- Activities

- Fields

- Access control (e.g. Warehouses, Branches, Banks, Job classes, Accounts, Contacts)

- eSignatures

in addition you could define the following information against each operator group:

- Program access

- eSignatures

In SYSPRO 6.1 you can now define any or all of these at the Role level. Once configured this means that the role assigned to the operator is used for activities, fields, access control, program access and eSignatures. In addition other newer features (such as Workflow) will also be configurable by role.

There is a new role table AdmRole (ADMRLE) that is used to store the list of roles and there is a new role organogram file (AMDRLO) that stores your role hierarchy. The role organogram is purely for documentary purposes.

Also for the first time it is now possible to define that each of these settings can be defined at the company level. For example when defining program access by role you can also configure program access by role by company.

From a developer perspective there should be little or no change as the standard functions in SYSPRO use the appropriately configured security levels. However it's worth noting the following issues:

Refreshing security settings

There is a new function called REFRESH-SECURITY-SETTINGS that will take account of the current operator, role and company and apply the current settings for each of the applicable areas. For example if you use the SYSPRO menu to switch roles we issue REFRESH-SECURITY-SETTINGS to force the new role information to be used.

New set of role base files

The previous files used to configure activities, fields, access control, program access have been retained 'as is'. In addition there are a new set of role based files to store this information when they are configured by role. The eSignature definition files already catered for role based configuration and did not require any change.

Use the standard functions to retrieve security settings

Any program that previously read the operator security or group access files should be changed to use the standard routines to access this information. This is because there are now separate role based version of these files and the logic must take account of various setup options. If you have previously made use of the copybook IMPSEC.WRK please read the latest comments in this copybook for it's usage.

Forcing an operator to change their password

The generic Password system includes a flag to force an operator to change their password the next time they login. There are two new functions that allow you to programmatically set or clear this flag against a specific operator.

The are.

SET-FORCE-CHANGE-PASSWORD

CLEAR-FORCE-CHANGE-PASSWORD

These functions are available in SYSPRO 6.1 port 29 onwards.

Browse and maintenance programs - standard messages

SYSPRO 6.1 has seen many of our traditional browse and maintenance programs being separated into two separate programs. There is a detailed document on the Support Zone covering this topic.

As part of this process we have standardized on some of the messages and confirmation dialogs. The following functions can be used for this purpose.

ASK-BRW-MAINT-CONFIRM-MBOX

ASK-BRW-MAINT-RET-MBOX

ADD-CHG-DEL-NOT-FOUND

Checking for memory leaks

When using Net Express data objects such as character arrays, ordered collections, sorted collections and dictionaries it can be useful to verify that you do not have any memory leaks. The functions OBJECT-COUNT-START and OBJECT-COUNT-END can be used for this purpose. This requires use of the copybook CLASS.WRK.

New function to assist when using WHERE LIKE clauses

There is a new function called SQL-GENERATE-WHERE-LIKE that can be used to help generate the LIKE clauses when they contain patterns.

For example using this function you can pass the regular wildcard '*John*' (any case) and it will be expanded to '%[Jj][Oo][Hh][Nn]%'.

System Audit log file function

SYSPRO 6.1 contains a new System Audit log capability. The previous job logging system is purely company based. However there is a new log file that is system-wide.

System Audit log information typically provides information about security breaches, notification of operator, group, role and password changes, when operators have been logged out and by whom. Also supervisor password changes, workflow overrides, system options and other serious changes to the system are also logged in this file.

You should not typically use the System Audit log to record regular and/or frequent transactional information. It is not intended that the System Audit log is populated with significant information in a short space of time.

For information about how to write information to this log see the function OUTPUT-SYSTEM-JOB-LOG.

Wildcard pattern matching routines

The wildcard pattern matching routines defined in PROFIND.PRO and FIND.WRK have had their documentation improved.

Also there are new functions to support larger fields. Previously a wildcard could be 30 characters and the field being searched 60 characters. This is now 50 and 255 characters respectively.

This is particularly useful for some newer fields such as the Contact Full name which is 100 characters.

Checking program security access

There is a new function called CHECK-MAINTENANCE-OTHER-PROG that can be used to verify whether another program can be run or not.

Editing dates

There is a new function called EDIT-DATE-TO-USER-FORMAT-CYMD that can be used to edit an 8 digit date into the short date, long date or report date format.

This is useful when editing a date from a file (typically stored in 8 digit format) or when editing from an Entry form that has been configured to use 8 digit dates.

It is also useful when you have a potential date prior to 1950 as the typical 6 digit date format only supports from 1 Jan 1950 through 31 Dec 2049. Using the full 8 digit date allows virtually any valid date to be used.

Generating file names from key fields

There is a new function called GENERATE-VALID-FILE-NAME that can be useful when using a field as part of a file name to ensure that you do not accidentally generate a file name that is not compatible with the operating system.

For example you may wish to generate a file name incorporating the current operator code. However if the operator code contains a colon (':') or an asterisk ('*') etc then the file name generated is invalid. This function will process the supplied string and return a string that only consists of letters and digits - including removing any embedded spaces.

New German dictionary

For the first time SYSPRO ships with a German dictionary. SYSPRO is now available in the following languages:

- English (native)

- French

- Spanish

- German

- Simplified Chinese

See the topic Language Translation for a complete description of the dictionaries available and how to add your own dictionaries if required.

Testing File Status Codes

A new Testing File Status Codes topic has been developed that summarizes the typical file status conditions that should be tested after each type of file access.

Translating text from server-side code

The Language Translation system that forms part of SYSPRO 6.1 typically provides translation of user interface elements. This system works with the client-side dictionary loaded when you first connect to SYSPRO.

However there maybe times when you need to apply server-side translation.

There is a function called TRANSLATE-TEXT that allows you to translate a single phrase from server-side code.

Similarly there is a set of functions (TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-LIST and TRANSLATE-TEXT-GET) that allow you to define a list of phrases to be translated and to retrieve the phrases once they have been translated.

Please read the remarks against these functions. If you simply wish to translate parts of the user interface then you should rather use the other language translation functions as they have been highly optimized for performance. Using these 'TRANSLATE-TEXT' functions will typically be slower that the client-side translation technology described in the rest of this topic.

Checking Contact Management Account and Contact access

The following functions related to Contact Management Account and Contact security have been documented for the first time:

VERIFY-ACCESS-ACCOUNT

VERIFY-ACCESS-CONTACT

FILTER-ACCESS-ACCOUNT

FILTER-ACCESS-ACCOUNT-MAINT

FILTER-ACCESS-CONTACT

FILTER-ACCESS-CONTACT-MAINT

Special characters in import or export files

If you develop code to import or export text files and wish to process special characters, such as TAB, LF or CR, then read this article Importing and Exporting Text Files that explains how to disable NULL insertion.

IMPACT.ERR has been renamed to IMPMSG.IMP

The file IMPACT.ERR has been an anomaly since SYSPRO was first developed as there were no other '.ERR' files.

For SYSPRO 6.1 we have renamed IMPACT.ERR to IMPMSG.IMP. As for all other .IMP files it is stored in the program folder.

The function LOOK-UP-ERROR that is used to extract the appropriate message from this file will still work as before.

Preventing the 800x600 warning from appearing

As standard SYSPRO programs require a minimum of a 800x600 resolution desktop - when SYSPRO loads it checks the size of the desktop and displays a warning message if the desktop is not at least 800x600.

However in the case of a completely custom application aimed at a hand held or similar device then this warning may not be required. You can suppress this message by moving the string 'anysiz' (exact case) to the site id defined in the system setup.

New or updated SDK sample programs

The following sample programs provide as part of the Software Development Kit are new (or have been revised) for SYSPRO 6.1:

- SDK006 Demonstrates use of a Docking pane, Toolbar, RTF object and Image viewer

- SDK007 Same as SDK006 plus a Display Form

- SDK008 Same as SDK007 plus an Entry Form

- SDK009 Assign Lists and Checkboxes using LIST.PRO

- SDK010 Invoke SRS Report passing XML

- SDK016 Skeleton program for help with developer training (see SDK016.DOC)

- SDKLCK Resource locking test harness

- SDKLOW Convert source code to lower case

- SDKSE2 SQL performance harness using ArCustomer and CmsContact tables

- SDKVER Utility to invert source code version comments

- SDKMSG Revised to add a task dialog test harness

- SDKCB6 Sample code to show opening an XML file and loading it into the SYSPRO XML parser

IMP files have been removed from source

Prior to SYSPRO 6.1 you will have noticed that the IMP files (e.g. IMPSEC.IMP) were included in the source folder, even though they were only accessed from the program folder at run-time.

For SYSPRO 6.1 we have changed our internal development processes so that we only define these IMP files in the program folder. The software development kit will no longer include these IMP files.

Module descriptions have been simplified

Module such as Accounts Payable and Accounts Receivable have traditionally been abbreviated to A/P and A/R. However for SYSPRO 6.1 we have simplified the abbreviations to AP and AR. You will notice that menus, program names, table descriptions etc. have been changed.

New Language and Nationality code IMP files

There is a new IMPLNG.IMP file that contains a list of languages. The language codes should be considered when adding custom languages to SYSPRO.

In addition there is a new IMPNAT.IMP file that contains a list of countries including a 2 character and 3 character code for each. This could be useful when implementing SYSPRO in a new territory.

Neither of these tables are currently used by standard SYSPRO programs in SYSPRO 6.1 but this could change in future. also this could be useful for 3rd party developers.

Source code version comments have been re-ordered

From SYSPRO 6.1 all standard SYSPRO source code programs have been changed so that version comments at the top of the source code are most-recent-first. This makes it much easier to quickly view the most recent changes. This will be seen when viewing the sample code from the Software Development Kit. For example SDK001.CBL.

To re-order the version comments we developed a utility for internal use. This utility SDKVER.EXE has been shipped as part of the Software Development Kit for you to use if required. Type the following from a command prompt to view it's parameters:

SDKVER /H

As these are purely comments it is not a requirement that you change your own code. This utility makes various assumptions about the structure of your source code and it's comments and is provided 'as is'.

See also

Debugging on Unix, Language Translation, IMPMSG.IMP, Importing and Exporting Text Files, PROBEGIN.PRO, PROFIND.PRO, SDK001.CBL, Resource Locking, Setting up a Development Environment for SYSPRO 6.1, Shared Inventory Files, SQL Server and ISAM Differences, SQL Server Tuning Code, Temporary files, Testing File Status Codes

ADD-CHG-DEL-NOT-FOUND, ASK-BRW-MAINT-CONFIRM-MBOX, ASK-BRW-MAINT-RET-MBOX, BUILD-TMPFIL, CALC-DATETIME-AGE, CALC-DATETIME-NEW-DATE, CALC-DATETIME-NEW-DATE-NUM, CHECK-MAINTENANCE-OTHER-PROG, CREATE-DIRECTORY-ON-CLIENT, CREATE-DIRECTORY-ON-SERVER, EDIT-DATE-TO-USER-FORMAT-CYMD, GENERATE-VALID-FILE-NAME, GET-COMPANY-LIST-ALL, GET-COMPANY-LIST-ALL-COMMA, GET-COMPANY-LIST-INV, GET-COMPANY-LIST-INV-COMMA, INVOKE-MESSAGE-BOX, INVOKE-MESSAGE-BOX-RESET, INVOKE-TASK-DIALOG, IS-LEAP-YEAR, LOOK-UP-ERROR, OBJECT-COUNT-END, OBJECT-COUNT-START, OUTPUT-SYSTEM-JOB-LOG, REFRESH-SECURITY-SETTINGS, RESOURCE-LOCK-ADD, RESOURCE-LOCK-ADD-MSG, RESOURCE-LOCK-DELETE, RESOURCE-LOCK-TEST, RESOURCE-LOCK-TEST-MSG, S-OSMKDR, S-OSMKDRS, SQL-GENERATE-WHERE-LIKE, TRANSLATE-TEXT, TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-LIST, TRANSLATE-TEXT-GET


What's new about SYSPRO 6.0 issue 010 SP2

As always each new issue of SYSPRO software has many new features and SYSPRO 6.0 Issue 010 SP2 is no exception. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

Many of the features in SP1 were only released as weekly ports and therefore did not appear on the initial SP1 CD. SYSPRO 6.0 Issue 010 SP2 is a consolidation of all the SP1 features and bug fixes. In addition a number of other features have also been released - these include:

Customized Docking Panes (Including an Executive View on the Main menu)

Greater use of Display and Entry Forms throughout the product

Over 260 eSignatures

Note that SYSPRO 6.0 Issue 010 SP2 released during March 2008 supersedes both SYSPRO 6.0 Issue 010 SP1 (May 2007) and the original SYSPRO 6.0 Issue 010 (2006) version. All the features of the original Issue 010 are also in Issue 010 SP1 and SP2.

Information for developers

Important - several changes to the SYSPRO 6.0 database have been made. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.0 issue 010 SP2 database changes.

Due to the file changes mentioned above and other copybook changes it is highly recommended that you recompile all Net Express source code program specifically for issue 010 SP2 using the latest copybooks from the issue 010 SP2 SDK - SDK610S2.ZIP.

Note: You must already be using SYSPRO 6.0 issue 009 or issue 010 or issue 010 SP1 before you convert your data files to SYSPRO 6.0 issue 010 SP2.

e.net solutions developers need not worry about changes to the SYSPRO 6.0 database as the business objects seamlessly handle any changes to the SYSPRO database.

As SP1 and SP2 are quite similar the remainder of the information relates to both SP1 and SP2. If you only want to see the SP1 specific information then see the topic What's new about SP1.

Developer Guides

As there is so much new technology in SYSPRO 6.0 Issue 010 we have authored and published developer guides that are aimed at developers using Net Express and SYSPRO.

These guides are available on the Support Zone (see the Developers section).

At the time that this topic was written the following developer guides were available:

SYSPRO Development 101

This guide is aimed at beginners developing code for SYSPRO using Net Express. It introduces the Software Development Kit and how to set up a development environment. Other topics include an overview of SYSPRO architecture including client/server, how to work with files, screensets, SQL Server and XML. There is a detailed walk-through of the sample program SDK001 demonstrating the basics of developing a SYSPRO program.

SYSPRO Development 201: User Controls

This guide introduces the topic of User Controls and how they fit into SYSPRO architecturally. A detailed walk-through of the sample programs SDK002 and SDK003 explains how to construct and code a program that has a listview with a toolbar. This document also contains a reference guide to listviews and toolbars.

SYSPRO Development 301: Data Objects

This guide introduces the concept of Data Objects and how they complement traditional working storage fields. Data Objects such as character arrays, ordered collections, sorted collections and dictionaries are covered in detail. A walk-through of the sample program SDK004 demonstrates these techniques.

SYSPRO Development 401: XML

This guide is introduces the topic of XML and how it is used in SYSPRO. XML is used extensively in SYSPRO programs for storing data, passing data and display purposes. The SYSPRO XML parser is discussed and a topic on how to call business objects from your Net Express programs is provided.

Docking Panes

One of the first things you will notice when you load the SYSPRO menu for the first time in SP2 is a much greater use of Docking Panes. These will replace the use of splitter controls throughout the entire product over time. The advantages of Docking Panes is that they are highly customizable in the end-users hands. You will also notice that all queries have already been changed to use these new controls.

It's very simple to re-arrange the panes, undock them to make them floating and even to associate panes with their neighbours producing a Tab effect. Also panes can be auto-hidden so that they only appear when the mouse hovers over them.

As with the rest of SYSPRO the arrangement of panes is remembered so that when you next load a program the panes are restored to have the same appearance as before. You can also reset the view back to the original if required.

Docking panes can be configured by Role if you want to prevent an operator changing the layout.

A sample program SDK005 has been provided to demonstrate a number of new features including Docking panes. It suggested that you spend a little time looking at the code in the user controls and screenset to see how this has been done.

From Issue 010 SP2 an end-user can add their own panes wherever there are already standard panes in SYSPRO. Due to this feature we will often develop a user interface using panes even if there is only a single pane.

Listviews (New)

The traditional listviews have not been changed in any way, however a new type of object called a Report Control has been included for the first time.

FYI - as most people have become used to the word 'Listview' in SYSPRO we will not be calling them Report Controls. Internally we are calling them 'New listviews' until they have replaced the older ones. To the outside world we are just calling them 'Listviews'.

A listview can be driven from your Net Express source code with very little dialog. This supports up to 100 columns each of 199 characters and a virtually unlimited number of rows.

In previous versions you had to page x number of rows into your screenset, use dialog to insert the rows and then return back to your program to retrieve more rows. This loop had to be coded to handle an unlimited rows and could consume a large part of your datablock. You were also limited to 50 columns each of 100 characters maximum. This is a thing of the past as your program can just write out as many rows as required.

Other features of the new listviews include:

- color by cell

- hyperlink by cell

- very fast sorting

- grouping and multiple levels of sort

- preview text can be passed and toggled by the operator

- operator sorting and grouping is remembered between sessions

- icons can be associated with any cell

- tooltips can be associated with any cell

- footers can be defined per column

- you can define fields as invisible or hidden in their initial state

- initial sort sequences and grouping can be configured

- column headings can be changed dynamically from your program

- initial columns can be frozen to prevent them scrolling

- VBScripting can be applied to the listview rows, cells or entire table

- print and print preview of the listview contents

In addition there is a high level of customization that can applied by the operator (or by Role if appropriate).

If an operator belongs to multiple roles then they can swap roles at any time causing the appropriate level of customization to appear.

Note that previous listviews and their functionality has been retained 100% so you can migrate to the new technology at your own pace.

Recompile for SP2

Most of this functionality was also available in Issue 010 SP1 however we have made much greater use of new listviews in SP2 and we have added more features in the end-users hands and improved the performance and stability of these objects.

In addition the listview technology creates temporary files in base\settings on both the server and client computers. We have changed the file naming convention to start all listview temporary files with LV_ for SP2.

Due to this change you MUST recompile your programs that use listviews for SP2 using the latest copybooks.

ContactId and GUIDs

A Contact Management System (CMS) was introduced in issue 010 SP1. This was developed using many of the new controls, however it is still a traditional SYSPRO application and therefore works in a client/server environment and with ISAM or SQL data storage.

One of the techniques used for the first time in CMS is that the key to the Contact master table (CRMCON - CrmContact) is a GUID.

A GUID is a Globally Unique Id. This is a 128 bit (16 character) field that is guaranteed to be unique.

Within your Net Express programs this is stored and used as a X(16) field. Also in a record layout it is stored as X(16). However in the data dictionary it is defined as a 'uniqueidentifier' column (the field is defined as Alphanumeric but also the field DDSFLD-GUID is a 'G').

In addition in a SQL Server environment the ContactId has a data type of 'uniqueidentifier'.

The data dictionary has had a few enhancements to cater for GUIDs and a few of the utility programs have also been changed.

See the topic Using GUIDs for additional information about working with GUIDs.

It is highly recommended that a GUID is never displayed or printed as it's a meaningless string to an operator. However some programs, such as generic utilities, may need to view the contents of a column. To assist with this there are two new functions for converting a 16 character GUID to an industry standard 38 character format. They are:

CONVERT-GUID16-TO-GUID38

CONVERT-GUID38-TO-GUID16

In addition if your program reads data generically and wants to show the key it is recommended that when passed a ContactId you show the Contact Name (rather than a GUID in any format). There is a new function that retrieves the Contact name when it is passed a ContactId. It is:

CMS-READ-CONTACT-NAME-FRM-GUID

The reverse allows you to return the ContactId given a Contact name.

CMS-READ-CONTACT-GUID-FRM-NAME

How does the data dictionary import know the field is a GUID?

When the data dictionary imports a record layout with a field defined as X(16), and if the ISAM field name contains the word 'GUID' or the Column names contains 'Guid', then it is flagged as a GUID. This is indicated by a the field having a type of 'Alphanumeric' and the field DDSFLD-GUID is set to 'G'.

Transferring files using ASCII format

The functions to transfer text (ASCII) files to and from a server have been updated to handle any size files.

COPY-FILE-TO-CLIENT-ASCII

COPY-FILE-TO-SERVER-ASCII

Data Dictionary Generic Viewer

The Data Dictionary Viewer (DDSBFI) has been updated to use new listviews. This allows you to quickly browse the data dictionary shipped as standard as part of SYSPRO.

In addition the Data Viewer (DDSBFD) that is invoked when you double-click on a table has been completely revised to use a new listview. This can be extremely useful in a development environment to browse and view your tables/files. One of the more useful features is the ability to view 'All Rows'. Of course when there is a large amount of data to be shown this can consume excessive resources - however when developing or testing new code it can be very useful. Remember that the 'Export to Excel' etc options could also be of use.

Why does my window / dialog box disappear in SP1/SP2?

If you find that your windows or dialog boxes seem to disappear when running with Issue 010 SP1 or SP2 read the appropriate FAQ in the topic about the IMPCENTR program.

Debugging on Unix

There is a new article to assist with developing and debugging on a Unix environment. See the topic Debugging on Unix

See also

Debugging on Unix, SYSPRO 6.0 Issue 010 SP1, SYSPRO 6.0 issue 010 SP2 database changes, Using GUIDs, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16, COPY-FILE-TO-CLIENT-ASCII, COPY-FILE-TO-SERVER-ASCII, CMS-READ-CONTACT-GUID-FRM-NAME, CMS-READ-CONTACT-NAME-FRM-GUID, IMPCENTR.


What's new about SYSPRO 6.0 issue 010 SP1

As always each new issue of SYSPRO software has many new features and SYSPRO 6.0 Issue 010 SP1 is no exception. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

Some of the major new areas for SP1 include:

Trade Promotions

Multiple A/P Payment cycles

Contact Management System (CMS) (Port 15)

SYSPRO Factory Scheduling (SFS) (Port 26)

Families and groupings (F&G) (Port 27)

Revised menu system

Docking Panes and New listviews

Greater use of Display and Entry Forms (e.g. Sales Order Entry)

Greater use of eSignatures

Note that SYSPRO 6.0 Issue 010 SP1 was released during May 2007 to supersede the original SYSPRO 6.0 Issue 010 version. All the features of the original Issue 010 are also in Issue 010 SP1.

Information for developers

Important - several changes to the SYSPRO 6.0 database have been made. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.0 issue 010 SP1 database changes.

Due to the file changes mentioned above and other copybook changes it is highly recommended that you recompile all Net Express source code program specifically for issue 010 SP1 using the latest copybooks from the issue 010 SP1 SDK - SDK610S1.ZIP.

Note: You must already be using SYSPRO 6.0 issue 009 or issue 010 before you convert your data files to SYSPRO 6.0 issue 010 SP1.

e.net solutions developers need not worry about changes to the SYSPRO 6.0 database as the business objects seamlessly handle any changes to the SYSPRO database.

The Contact Management System was released as an 'Early Release' component with SYSPRO 6.0 Issue 010 SP1. The initial release that can be installed is available from port 15.

Developer Guides

As there is so much new technology in SYSPRO 6.0 Issue 010 we have authored and published developer guides that are aimed at developers using Net Express and SYSPRO.

These guides are available on the Support Zone (see the Developers section).

At the time that this topic was written the following developer guides were available:

SYSPRO Development 101

This guide is aimed at beginners developing code for SYSPRO using Net Express. It introduces the Software Development Kit and how to set up a development environment. Other topics include an overview of SYSPRO architecture including client/server, how to work with files, screensets, SQL Server and XML. There is a detailed walk-through of the sample program SDK001 demonstrating the basics of developing a SYSPRO program.

SYSPRO Development 201: User Controls

This guide introduces the topic of User Controls and how they fit into SYSPRO architecturally. A detailed walk-through of the sample programs SDK002 and SDK003 explains how to construct and code a program that has a listview with a toolbar. This document also contains a reference guide to listviews and toolbars.

SYSPRO Development 301: Data Objects

This guide introduces the concept of Data Objects and how they complement traditional working storage fields. Data Objects such as character arrays, ordered collections, sorted collections and dictionaries are covered in detail. A walk-through of the sample program SDK004 demonstrates these techniques.

SYSPRO Development 401: XML

This guide is introduces the topic of XML and how it is used in SYSPRO. XML is used extensively in SYSPRO programs for storing data, passing data and display purposes. The SYSPRO XML parser is discussed and a topic on how to call business objects from your Net Express programs is provided.

Role based customization

For the first time you can assign a Role to an operator. See the Role Tab in the main operator maintenance dialog box.

Using this technique it's possible for a supervisor to customize the look and feel of the product for a specific role. Once saved the operators who belong to that role will see the product as defined and cannot change it themselves.

Also when using Role based customization display and entry forms and any VB Scripts are also take account of the current operator's role.

Docking Panes

One of the first things you will notice when you load the SYSPRO menu for the first time in SP1 is the use of Docking Panes. These will replace the use of splitter controls throughout the entire product over time. The advantages of Docking Panes is that they are highly customizable in the end-users hands. You will also notice that most queries have already been changed to use these new controls.

It's very simple to re-arrange the panes, undock them to make them floating and even to associate panes with their neighbours producing a Tab effect. Also panes can be auto-hidden so that they only appear when the mouse hovers over them.

As with the rest of SYSPRO the arrangement of panes is remembered so that when you next load a program the panes are restored to have the same appearance as before. You can also reset the view back to the original if required.

Docking panes can be configured by Role if you want to prevent an operator changing the layout.

A sample program SDK005 has been provided to demonstrate a number of new features including Docking panes. It suggested that you spend a little time looking at the code in the user controls and screenset to see how this has been done.

Listviews (advanced)

The traditional listviews have not been changed in any way, however a new type of object called a Report Control has been included for the first time.

FYI - as most people have become used to the word 'Listview' in SYSPRO we will not be calling them Report Controls. Internally we are calling them 'advanced listviews' until they have replaced the older ones. To the outside world we are just calling them 'Listviews'.

For the first time the contents of a listview can be driven from your Net Express source code with very little dialog. This supports up to 100 columns and a virtually unlimited number of rows.

In previous versions you had to page x number of rows into your screenset, use dialog to insert the rows and then return back to your program to retrieve more rows. This loop had to be coded to handle an unlimited rows and could consume a large part of your datablock. You were also limited to 50 columns. Now that is a thing of the past as your program can just write out as many rows as required.

Other features of the new listviews include:

- color by cell

- hyperlink by cell

- very fast sorting

- grouping and multiple levels of sort

- preview text can be passed and toggled by the operator

- operator sorting and grouping is remembered between sessions

- icons can be associated with any cell

- Tooltips can be associated with any cell

- footers can be defined per column

- you can define fields as invisible or hidden in their initial state

- initial sort sequences can be configured

- column headings can be changed from your program

- initial columns can be frozen to prevent them scrolling

- VBScripting can be applied to the listview rows, cells or entire table

- print and print preview of the listview contents

In addition there is a high level of customization that can applied by the operator (or by Role if appropriate).

If an operator belongs to multiple roles then they can swap roles at any time causing the appropriate level of customization to appear.

Note that previous listviews and their functionality has been retained 100% so you can migrate to the new technology at your own pace.

ContactId and GUIDs

There is a new Contact Management System (CMS) included in Issue 010 SP1. This is developed using many of the new controls, however it is still a traditional SYSPRO application and therefore works in a client/server environment and with ISAM or SQL data storage.

One of the techniques used for the first time in CMS is that the key to the Contact master table (CRMCON - CrmContact) is a GUID.

A GUID is a Globally Unique Id. This is a 128 bit (16 character) field that is guaranteed to be unique.

Within your Net Express programs this is stored and used as a X(16) field. Also in a record layout it is stored as X(16). However in the data dictionary it is defined as a 'uniqueidentifier' column (the field is defined as Alphanumeric but also the field DDSFLD-GUID is a 'G').

In addition in a SQL Server environment the ContactId has a data type of 'uniqueidentifier'.

The data dictionary has had a few enhancements to cater for GUIDs and a few of the utility programs have also been changed.

See the topic Using GUIDs for additional information about working with GUIDs.

It is highly recommended that a GUID is never displayed or printed as it's a meaningless string to an operator. However some programs, such as generic utilities, may need to view the contents of a column. To assist with this there are two new functions for converting a 16 character GUID to an industry standard 38 character format. They are:

CONVERT-GUID16-TO-GUID38

CONVERT-GUID38-TO-GUID16

In addition if your program reads data generically and wants to show the key it is recommended that when passed a ContactId you show the Contact Name (rather than a GUID in any format). There is a new function that retrieves the Contact name when it is passed a ContactId. It is:

CMS-READ-CONTACT-NAME-FRM-GUID

The reverse allows you to return the ContactId given a Contact name.

CMS-READ-CONTACT-GUID-FRM-NAME

How does the data dictionary import know the field is a GUID?

When the data dictionary imports a record layout with a field defined as X(16), and if the ISAM field name contains the word 'GUID' or the Column names contains 'Guid', then it is flagged as a GUID. This is indicated by a the field having a type of 'Alphanumeric' and the field DDSFLD-GUID is set to 'G'.

Transferring files using ASCII format

The functions to transfer text (ASCII) files to and from a server have been updated to handle any size files. See the detail notes describing each function for the specific release date of each function.

COPY-FILE-TO-CLIENT-ASCII

COPY-FILE-TO-SERVER-ASCII

Why does my window / dialog box disappear in SP1?

If you find that your windows or dialog boxes seem to disappear when running with Issue 010 SP1 read the appropriate FAQ in the topic about the IMPCENTR program.

Debugging on Unix

There is a new article to assist with developing and debugging on a Unix environment. See the topic Debugging on Unix

Context Help Marked for Obsolescence

Important note - As the Windows .HLP file format is obsolete from Windows Vista onwards SYSPRO will be removing any context help in the 2008 time scale. The topic Creating Context Sensitive Help will no longer be appropriate.

See also

Debugging on Unix, SYSPRO 6.0 issue 010 SP1 database changes, Using GUIDs, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16, COPY-FILE-TO-CLIENT-ASCII, COPY-FILE-TO-SERVER-ASCII, CMS-READ-CONTACT-GUID-FRM-NAME, CMS-READ-CONTACT-NAME-FRM-GUID, IMPCENTR.


What's new about SYSPRO 6.0 issue 010

As always each new issue of SYSPRO software has many new features and SYSPRO 6.0 Issue 010 is no exception. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

Some of the major new areas include:

Reporting services

Trade Promotions

Entry Forms (e.g. Sales Order Entry)

Costing by Warehouse and Multiples Bins by Warehouse

Language Translation system

Electronic Signatures

Note that SYSPRO 6.0 Issue 010 SP1 was released during May 2007 to supersede the original Issue 010 version. All the features of the original Issue 010 are also in Issue 010 SP1.

Information for developers

Important - several changes to the SYSPRO 6.0 database have been made. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.0 issue 010 database changes.

Due to the file changes mentioned above and other copybook changes it is highly recommended that you recompile all Net Express source code program specifically for issue 010 using the latest copybooks from the issue 010 SDK - SDK610.ZIP.

Note: You must already be using SYSPRO 6.0 issue 009 before you convert your data files to SYSPRO 6.0 issue 010.

e.net solutions developers need not worry about changes to the SYSPRO 6.0 database as the business objects seamlessly handle any changes to the SYSPRO database.

SYSPRO 6.0 Issue 010a

SYSPRO 6.0 Issue 010 was our largest single release of functionality and technology. We have many customers running successfully on this version of software. Inevitably there have been a number of fixes and a number of additional enhancements that did not make it onto the original CD.

We normally cater for ongoing bug fixes and enhancements using a weekly porting process - and this will continue...

However we have also decided to produce an updated Issue 010 CD called 'SYSPRO 6.0 Issue 010a'.

This contains the original Issue 010 contents together with a set of consolidated bug fixes and enhancements include the fixes from port 01 through port 15.

Important - there are no additional database or technology changes from the original SYSPRO 6.0 Issue 010 CD.

It is highly recommended that all new SYSPRO sites from the beginning of 2007 use the Issue 010a CD rather than the original CD.

See the Support Zone for more information about Issue 010a.

Data Dictionary improvements

The data dictionary system has been substantially revised for issue 010.

Data Dictionary data file changes

The previous data dictionary data files stored in base\dd on the server are retained largely unchanged. These are minor changes but include different record lengths and/or keys. If you have any programs that access these files directly then you will need to recompile them using the latest Software Development Kit (SDK610.ZIP).

In addition to the existing data dictionary files, a new set of files are now shipped that are designed to be much easier to use.

The new files are:

DDSTAB.DAT - table definitions

DDSCOL.DAT - column definitions

DDSIDX.DAT - index definitions

DDSFKY.DAT - link definitions

The reasons that these files are easier to use include:

  • The primary key to the table definition file (DDSTAB) is the table name (previously the 6 character file code was the primary key)

  • The primary key to the column definition file (DDSCOL) is the table and column name (previously the 6 character file code and a sequence number was the primary key)

  • When a field is defined as occurring a number of times each occurrence will be stored in the DDSCOL file (previously the DDSFLD only contained one occurrence and you, as a developer, had to generate the multiple occurrences)

  • When a file layout is duplicated multiple times (e.g. for MRP snapshot files) then each copy of the file is defined in the DDSTAB, DDSCOL, DDSIDX and DDSFKY files (previously only the original file definition was stored in DDSFIL and you, as a developer, had to generate the multiple file definitions by using the DDSSUB file)

DDSBFI - data viewer

The Data dictionary file viewer utility (DDSBFI) has been completely revised for issue 010. The entire list of files is shown in a listview. This can be sorted and exported if required - use Ctrl+F1 to see the valid options.

You can view the table properties - this is also shown in a completely new format. The table details and keys are shown at the top of the window and all the columns are shown below. Again these can be sorted and exported if required.

You can view the physical data using a completely new format. This allows you to see data in a listview with the benefits that provides. Primary key columns are shown with an asterisk in the column name. If required the 'Classic' view is also still available.

Foreign keys - SQL Diagrams

For the first time SYSPRO now has Foreign Keys defined in it's SQL Server database. This is particularly useful when using SQL Server Diagramming as it uses Foreign Keys to understand the relationship between tables.

The Foreign Keys defined are designated 'WITH NOCHECK' so that they are not used to enforce data integrity rules. However they can still be used for the SQL Server Diagramming.

Note that during any conversion all Foreign Keys will be dropped, the conversion will take place and then all Foreign Keys will be re-applied. All standard SYSPRO Foreign Keys start with the name 'Syspro_'.

If errors occur when these Foreign keys are being applied then a log of any errors is written to ?_ForeignKeyError.TXT (where ? is the company). If any errors are returned it is strongly recommended that you run the SQL Server Diagnostic program (IMPDG6) to verify and fix any problems with your database. Foreign Keys are not required for SYSPRO to run successfully however an error when adding Foreign Keys means that your database is not correct and could lead to some other problem.

A/R Statement format moved to new ARSFMT file

From issue 010 onwards the A/R Statement format has been moved to a new ARSFMT file. This has been done to support multiple A/R statement formats. This file resides in the work folder and remains as C-ISAM. See the ARSFMT.MAI record layout in the SDK for the new file layout. Note that these format records are identical to the previous ones except for the key.

Prior to issue 010 the A/R Statement format was stored in the company control file (ADMCTL) using various record types.

The issue 010 conversion wizard will move the existing format to the new ARSFMT file. Note that the old formats will be removed from the company control file.

Important: If you have any applications that use or access the A/R Statement format directly then they should be re-coded to use the new ARSFMT file.

New Entry Forms used for the first time

For the first time SYSPRO 6.0 issue 010 supports Entry Forms - sometimes simply called Forms. These are modified version of listviews with two columns. One with a caption and the second with the data to be shown/captured.

Entry Forms provide a sophisticated method of presenting data and allowing the operator to add/edit data. The user-interface looks more appealing than previous entry fields and is highly customizable in the end-users hands.

Initially a few programs (such as Sales Order Entry and Purchase Order Entry) have been upgraded to use this new interface style. Over time more programs will be changed.

The new user-interface style is quite different from a programming perspective - moving on from the Property controls (Display Forms) first seen in the Query programs in Issue 009.

A sample program called SDKEDT has been provided to provide a taste for some of the new features.

A set of documentation explaining how to program this new interface style will be provided during 2007.

Highly revised listview and toolbar user-control logic

The listview copybooks (LIST*.WRK and LIST*.PRO in copy60) have been highly revised for issue 010. This is largely to support the Entry Forms mentioned above, however listviews have been enhanced in a number of areas. Due to these changes you must recompile all programs that use listviews.

The toolbar copybooks (TOOL*.WRK and TOOL*.PRO in copy60) have been highly revised for issue 010. This is largely to support new and enhanced toolbar logic. Due to these changes you must recompile all programs that use toolbars.

New SYSPRO Reporting Services (SRS) available for the first time

For the first time SYSPRO 6.0 issue 010 supports reporting using Crystal Reports technology.

This provides all the power of Crystal Reports XI including sophisticated formatting.

However our implementation does not simply use Crystal to produce reports directly from the database (SQL or ISAM) as you would do with a standalone version of Crystal. Rather the Reporting Services Framework uses the XML output from SYSPRO Business objects as the data source.

This has many benefits including:

- data source dependent (it works with both SQL and ISAM)

- all business logic/rules are applied (security, rounding, conversion factors, currency...)

- simplified creation of complex reports (the business objects have the complexity)

In addition a set of schemas (XSD) are used to configure the valid input and output to the business object. This allows a supervisor to be able to configure the Form shown at run time and to be able to customize the actual report produced.

Issue 010 already has over a hundred (relatively simple) reports provided using this new technology. During the issue 010 life cycle many more will be added.

It is our intention for SYSPRO 7.0 to replace almost all of the existing reports with this technology.

You can also use this technology to produce documents. Initially A/R Statements can be printed using SRS, in the near future many other documents will be available, such as invoices, delivery notes and purchase orders.

SYSPRO Reporting Services (often abbreviated to SRS) requires Windows 2000 or Windows XP on the client. Windows 98 is not supported. The technology works in a client/server environment as a client application and therefore will work on both Windows and Unix server systems.

Completely new Language Translation system

The Language translation system used in issue 009 and prior versions relied on the creation of Net Express library files (e.g. ENCORE07.LBR) in the base folder on the Client PC. When configured correctly the Dialog system would then automatically use these library files to translate the text on various objects into a foreign language.

However this technology was limited and was not extensible by SYSPRO.

From issue 010 we have developed our own Language Translation system. The benefits include:

  • The dictionaries are plain text files that can be viewed and edited using any text editor

  • The dictionaries are stored on the server and self-healed to the client - this allows SYSPRO to provide more regular updates to keep in line with the latest software changes

  • More types of text objects are translatable

  • A single dictionary is provided for each language for consistency

  • The translation uses smart logic to handle variable data embedded within message text

  • SRS (Reporting Services) uses the new technology so that all run-time prompts and report headings are automatically translated

  • You can create custom dictionaries using a simple text editor provided with SYSPRO. This allows terminology changes (such as 'Stock code' to 'Part number') to be quickly and conveniently applied.

As a Net Express developer there are a few best practices to get the best out of the new system however apart from those there is nothing you have to do to have your applications appear in the required language.

See the topic Language Translation for more information.

SQL Server JOINs up to 1000 characters supported

When you have sophisticated JOIN logic between tables the issue 009 limitation of 215 characters could be a problem. From issue 010 you can specify a string up to 1000 characters for each JOIN.

See the topic SQL Server Tuning Code for more information.

Client/Server improved ASCII file copy facility

From issue 010 there is no limit to the size of data file that can be transferred using the COPY-FILE-TO-CLIENT-ASCII function.

Calling Business objects from your Net Express programs is now complete

From issue 009 there was limited support for your Net Express programs calling Business objects directly.

All the Business objects shipped with issue 010 now support this functionality.

This is described in the topic Calling Business Objects Overview. In addition there is walk through of a new sample program SDKCB1 demonstrating calling the A/R Query (ARSQRY) business object.

There are several advantages to coding your Net Express applications to call business objects directly and there are no e.net licensing implications when calling business objects from Net Express programs.

e.net solutions business objects

e.net solutions has been developed rapidly since it was first released with SYSPRO 6.0 issue 006. There are now dozens of business objects that handle queries into the SYSPRO system. Many of these provide extensive query capabilities into the appropriate module.

In addition there has been an emphasis on developing Transaction.Post and Setup.Add, Setup.Update, Setup.Delete business objects. These include posting sales orders, purchase orders, inventory movements, requisitions, invoices, quotations and job transactions.

Now that e.net solutions has been available for many years and there have been many successful implementations in a large number of customer sites. Several of which have over 200-300 concurrent users and some as high as 1000 users.

Developers have already used applications developed in VB, VB.NET, C#, ASP 3.0, ASP.NET and Delphi to invoke e.net Business objects - including standalone and web based applications using COM, DCOM and COM+.

Note that the Business object reference library is not being maintained in this help file from issue 010 onwards. The reason is that the Business objects are being developed and maintained at such a quick pace that this help file is soon out-of-date. You should use the e.net Business Object Reference Library on the Support Zone at www.syspro.com for more extensive documentation.

See also

SYSPRO 6.0 issue 010 database changes, Calling Business Objects Overview, e.net solutions, e.net Licensing Overview, business objects, Transaction.Post


What's new about SYSPRO 6.0 issue 009

As always each new issue of SYSPRO software has many new features and SYSPRO 6.0 issue 009 is no exception. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

Major new areas include:

Reengineered Assets Module

New Electronic Funds Transfer (EFT) module

New Return Merchandise Authorization (RMA) module

New Inventory Forecasting (IOP) module

Structured G/L codes

Reengineered help using HTML

Information for developers

Important - several changes to the SYSPRO 6.0 database have been made. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.0 issue 009 database changes.

Note: You must already be using SYSPRO 6.0 issue 008 before you convert your data files to SYSPRO 6.0 issue 009.

e.net solutions developers need not worry about changes to the SYSPRO 6.0 database as the business objects seamlessly handle any changes to the SYSPRO database.

SYSPRO 6.0 issue 009 has been developed using Net Express 4.0. Prior versions of SYSPRO 6.0 have been developed using Net Express 3.1. If you have not yet installed Net Express 4.0 then read the topic Installing Net Express 4.0 to help you with the installation. Due to this change you should carefully read the relevant section below.

The name of the SDK files has been changed to make it clearer which version of the SDK applies to which version of SYSPRO. The new naming convention is SDK999.ZIP where 999 represents the version and issue of SYSPRO. For example the SYSPRO 6.0 issue 009 SDK is named SDK609.ZIP.

Also note that From January 2005 the SDK ZIP file do not contain Encore 4.0 information. This can be downloaded separately from the Support Zone if required.

Net Express 4.0 overview

SYSPRO 6.0 issue 009 has been developed using Net Express 4.0. Prior versions of SYSPRO 6.0 have been developed using Net Express 3.1.

Generally Net Express 4.0 is very similar to Net Express 3.1. From a developers perspective the IDE, Compiler and Animator are almost identical. Projects created in NE 3.1 can be converted to NE 4.0 format and used immediately.

In addition when you install Net Express 4.0 you can retain your Net Express 3.1 system and work with the two versions independently.

One major change when using Net Express 4.0 is that the Net Express 4.0 run-time system requires a license to be installed on each client running the application. When SYSPRO 6.0 issue 009 is installed this license will be installed. Due to this license, note that you cannot simply copy the run-time system from one computer to another. Your programs and screensets can be copied as normal.

Net Express 4.0 - Developers notes

Please note the following points relating to Net Express 4.0

Recompile recommended

Whilst the majority of applications compiled to 'INT' or 'GNT' using NE 3.1 should run unchanged on the NE 4.0 run time, it is recommended that you recompile your applications using Net Express 4.0. During our informal testing all Net Express 3.1 intermediate code programs ran successfully with issue 009.

Create a NX variable to indicate the version of Net Express being used

When you install Net Express 4.0 you can retain your Net Express 3.1 system and work with them independently. To avoid accidentally using the wrong version of Net Express with the wrong version of SYSPRO source code we have implemented a new environment variable called NX. This should have the value 4.0 or 3.1 as appropriate.

It is recommended that your Net Express command prompts are configured to set this variable appropriately. For example your CREATENV.BAT file should be changed to add the following:

SET NX=4.0

Your Net Express 3.1 command prompt CREATENV.BAT should have:

SET NX=3.1

The SYSPRO issue 009 SDK batch file COMPILE.BAT will not proceed unless NX is set to 4.0

Reserved words

There are a number of new reserved words in Net Express 4.0. We have changed any reference to the following reserved words to different names. You may have used other names that are now reserved words in Net Express 4.0.

XML

OVERRIDE

More strict syntax checking

The Net Express 4.0 compiler is more strict on syntax checking. Due to this we found that some of our user-controls (the ones named ??????W1.CBL) had redundant/incorrect procedural code in object definitions. These incorrect code fragments were commented out as they served no purpose.

OpenESQL calls return Unicode for system tables

The OpenESQL ODBC calls return Unicode when querying SQL Server system tables. This includes SELECT statements on the INFORMATION_SCHEMA tables. For example:

SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES

now returns table names in Unicode. This is correct as the column TABLE_NAME is defined as Unicode, however when using Net Express 3.1 the values were returned as ASCII. This required a minor change to the code to fetch the result set.

If you have coded EXEC SQL calls then you may have to re-code your application to take account of Unicode result sets. Note that standard SYSPRO tables do not use Unicode.

If you are using the standard SQL file handlers or optimized code functions these have been adjusted to handle possible Unicode results.

Change to X"91" directory scan function

The output of this function has been changed to conform with the Net Express documentation. You should verify any program that uses the X"91" - function 69 - call to make sure that it works correctly. Specifically that the file attributes are passed correctly. See the topic Searching for Files for information about new functions that have been provide to make directory scanning easier and more consistent.

Dialog System creates 88 levels and clears NLS basename

The initial version of the Dialog System that was shipped with Net Express 4.0 had two bugs that caused problems.

The first is that all datablock copybooks were created with 88 levels for each single character numeric field, the second is that the NLS basename is lost. SYSPRO have received patches to correct these two bugs, however the FixPacks are currently still being developed by Micro Focus (July 2004).

If you do not yet have access to these Fixpacks then you can use the Dialog System that ships with Net Express 3.1.

Licensing

One major change when using Net Express 4.0 is that the Net Express 4.0 run-time system requires a license to be installed on each client running the application. When SYSPRO 6.0 issue 009 is installed this license will be installed. Due to this license, note that you cannot simply copy the run-time system from one computer to another. Your programs and screensets can be copied as normal.

Generic Password System for Program Functions

From issue 009 onwards, programs that provide password control of various functions/activities (such as preventing entry of a credit note) use the Generic password system.

A new text file IMPPSS.IMP defines the available passwords and their descriptions. A Custom version of this file (CUSPSS.IMP) can be used by developers to define their own passwords.

Prior to issue 009 these function passwords were stored in the company control file as 4 character unencrypted strings. The issue 009 conversion wizard will convert the old passwords to the new format and blank out the 4 character fields used previously.

Important: If your application used these old passwords then you must re-code your application to use the password system as the old passwords have been set to spaces. See the ASK-PASSWORD and related topic descriptions.

Also note that when calling standard SYSPRO programs, such as the Editor (EDIT.WRK) and the Logic to determine/request the posting month/period (MON.WRK) that they may require a password to be passed. In each case these linkages have been enhanced to allow a 30 character password to be passed to the program. You should re-code your application to use the new 30 character password. You may require your application to request a 30 character password field to pass to these programs.

Sales Order stationery formats moved to new SORFMT file

From issue 009 onwards various Sales Order document formats have been moved to a new SORFMT file. This file resides in the work folder and remains as C-ISAM. See the SORFMT.MAI record layout in the SDK for the new file layout. Note that these format records are identical to the previous ones except for the key.

Prior to issue 009 the majority of these stationery formats were stored in the company control file (ADMCTL) using various record types. In addition some of the formats were stored in the SORDFM file.

The issue 009 conversion wizard will move these formats to the new SORFMT file. Note that the old formats will be removed from the company control file and the SORDFM file will be removed.

Important: If you have any applications that use or access these formats directly then they should be re-coded to use the new SORFMT file.

The stationery formats affected include:

- Delivery notes

- Order acknowledgements

- Invoices

- Dispatch notes

- Supply chain transfer documents

New SQL Server support functions in issue 009

There are three new functions that can be useful when optimizing your code for SQL Server environments.

SQL-GET-COLLATION

This function can be used to retrieve the SQL Server collation name for the current SYSPRO database. See the topic SQL Server Creating Temporary Tables for a practical example of how this function can be used.

SQL-EXPAND-PARAMETERS

This function can be used when you wish to execute your own SQL Server command using SQL-EXECUTE-COMMAND but require to include a WHERE string that contains parameters. You can build up a parameterized string with a list of the values for each parameter and then PERFORM SQL-EXPAND-PARAMETERS. This will return a string with the appropriate parameters replaced. This function handles alphanumeric, numeric and date parameters, all of which require special processing for specific values.

SQL-EXPAND-TABLES

This function allows you to pass a list of tables (and company id's for each table if required). After being invoked the function returns a Database..Tablename definition for each table. if the table does not reside in the current SYSPRO database then the Database prefix is built - if the table resides in the current database then no prefix is added and just the original table name is returned.. This is particularly useful for tables that use the shared inventory or shared general ledger id's.

See the topic SQL Server Tuning Code for more details about optimizing your code for SQL Server.

New functions to call business objects from your Net Express programs

Until now only e.net Solutions developers using a COM enabled language such as VB, VB.NET, C++, C# could access business objects.

From SYSPRO 6.0 issue 009 Net Express developers can access business objects directly from their Net Express program.

This is described in the topic Calling Business Objects Overview. In addition there is walk through of a new sample program SDKCB1 demonstrating calling the A/R Query (ARSQRY) business object.

There are several advantages to coding your Net Express applications to call business objects directly and there are no e.net licensing implications when calling business objects from Net Express programs.

SYSPRO Help

The on-line help system has been completely re-engineered using HTML. Previously the Windows HLP file format had been used. The system has been renamed to 'SYSPRO Help' to avoid the confusion of the phrase 'on-line'.

See the topic Creating Help for an article explaining what you need to know to create your own help files that will have a similar look-and-feel to standard SYSPRO Help.

Note that the format of the IMPHLP.IMP file has changed and this affects the custom version (CUSHLP.IMP). You can use CUSIMP.IMP to direct the F1 key to show a CHM file as well as the new format HTML style help.

e.net solutions business objects

e.net solutions has been developed rapidly since it was first released with SYSPRO 6.0 issue 006. There are now dozens of business objects that handle queries into the SYSPRO system. Many of these provide extensive query capabilities into the appropriate module.

In addition there has been an emphasis on developing Transaction.Post and Setup.Add, Setup.Update, Setup.Delete business objects. These include posting sales orders, purchase orders, inventory movements, requisitions, invoices, quotations and job transactions.

Now that e.net solutions has been available for over two years there have been many successful implementations in a large number of customer sites. Several of which have over 200-300 concurrent users and some as high as 1000 users.

Developers have already used applications developed in VB, VB.NET, ASP 3.0, ASP.NET and Delphi to invoke e.net business objects - including standalone and web based applications using COM, DCOM and COM+.

See the latest e.net business object library on the Support Zone at www.syspro.com for more extensive documentation.

See also

SYSPRO 6.0 issue 009 database changes, Calling Business Objects Overview, Searching for Files, e.net solutions, e.net Licensing Overview, business objects, Transaction.Post, Generic password system, IMPHLP.IMP, IMPPSS.IMP


What's new about SYSPRO 6.0 issue 008

As always each new issue of software has many new features and SYSPRO 6.0 issue 008 is no exception. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

Information for developers

Important - several changes to the SYSPRO 6.0 database have been made. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.0 issue 008 database changes. In particular note that some A/P and Cash book files have been re-organized and require a file conversion. Any programs that access these files will need to be recompiled before using them with SYSPRO 6.0 issue 008.

In addition some General Ledger tables have had their line numbers changed from numeric to alphanumeric - decimal(5,0) to char(5). You may need to change your code if your programs access these fields. See the article General Ledger Line Numbers. The new routines INCREMENT-LINE-X5 and DECREMENT-LINE-X5 should be used to change these line numbers.

e.net solutions developers need not worry about changes to the SYSPRO 6.0 database as the business objects handle the changes.

e.net licensing

Note that from Issue 008 e.net licensing will be more strictly enforced. This will entail you receiving a LICENSE.XML file that must be imported into your system and then apportioning your licenses across various operators.

Note that this must be performed to access any e.net business object, the e.net web-based applications and when using the Document Flow Manager.

When you convert an issue 007 company to issue 008 you will have a 30 day grace period to implement the new licensing. Once you use the 'Configure e.net License' Wizard the new license system will be in-force (and the grace period will fall-away).

For more details about e.net licensing see the topic e.net Licensing Overview and the Support Zone at www.syspro.com.

e.net licensing - Functional areas

e.net is licensed at the functional area level. If you develop e.net business objects then you must define a 78 level constant with the name of the Functional area to which your program belongs. For business objects that do not belong to a standard SYSPRO functional area you should use the special functional area named 'EnetSystem'. This special functional area can be run without any licensing limitations - you only need the e.net System Manager to be installed against the company.

For example add the following line to your source code in working storage:

78 FunctionalArea VALUE 'EnetSystem'.

Security - Preventing access to Browses

You can use the group security maintenance function to prevent browse programs from being run. Until now configuring a browse program as 'access denied' meant that you were prevented from using the maintenance functions of the browse. ie. you could not prevent an operator from viewing items in a browse.

From issue 008 you can configure the access to browse programs as 'Denied', 'Browse only' or 'Allowed'.

- 'Denied' means that the browse cannot be run at all - you will receive an 'Access Denied' message.

- 'Browse Only' means that you can run the browse program, view/select items but you cannot maintain items.

- 'Allowed' means you have full access to the browse program including any maintenance functions.

Note that some programs are treated as browses for security purposes. These include:

- Generic rich-text notepad. ('Denied' means you cannot access the notepad at all, 'Browse Only' means that you can view notes and 'Allowed' means that you can view and edit notes)

- Factory calender browse/maintenance

- Multimedia play/edit

Browse programs using BROWSE.PRO will automatically include the appropriate security checking as BROWSE.PRO includes the CHECK-MAINTENANCE function internally.

In addition if you have a program that must work similarly to a browse program then you can use the CHECK-MAINTENANCE function directly.

Administration - Viewing changes to Company Setup Options

From issue 008 you can view an audit trail of all changes to Company Setup options. Each company setup program has been enhanced to output an amendment journal of all changes. To view and/or print this information run the program Setup, Security, Setup Amendment Journal...

Updated graphics libraries

The Graphics libraries (DLL's) have been updated to a more recent specification. The programs that call graphics functions have been updated to handle screen refreshes. If your program calls the generic graphics program (IMPGRP) then this program will handle the changes. See the sample program (SDKGRP) for sample code demonstrating how to call the generic graphics program.

e.net solutions business objects

e.net solutions has been developed rapidly since issue 006. There are now dozens of business objects that handle queries into the SYSPRO system. Many of these provide extensive query capabilities into the appropriate module.

In addition there has been an emphasis on developing Transaction.Post business objects. These include posting sales orders, purchase orders, inventory movements, requisitions, invoices and jobs transactions.

Now that e.net solutions has been available for over a year there have been many successful implementations in a large number of customer sites. Developers have already used applications developed in VB, VB.NET, ASP 3.0, ASP.NET and Delphi to invoke e.net business objects - including standalone and web based applications using COM, DCOM and COM+.

See the latest e.net business object library on the Suport Zone at www.syspro.com for more extensive documentation.

See also

SYSPRO 6.0 issue 008 database changes, e.net solutions, e.net Licensing Overview, business objects, Transaction.Post


What's new about SYSPRO 6.0 issue 007

As always each new issue of software has many new features and SYSPRO 6.0 issue 007 is no exception. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

Information for developers

Important - some changes to the SYSPRO 6.0 database have been made. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.0 issue 007 database changes. In particular note that the P/O Supplier/Stock code Information file has a new alternate index. If you are developing code for C-ISAM based systems that access PORSST you will need to recompile them before using them with SYSPRO 6.0 issue 007.

e.net solutions developers need not worry about changes to the SYSPRO 6.0 database as the business objects handle the changes.

SYSPRO source code samples

The SYSPRO 6.0 Software Development Kit has a few more Source code sample programs to help developers see how to use a standard function or use a programming technique. Download the latest SDK ZIP file and see the programs called SDK*.CBL.

Developing Listviews (important)

A large amount of work has been done to improve listviews for issue 007.

It is strongly recommended that the source code for your listviews are regenerated (as described below) to be able to take account of new listview functionality.

To make listview development simpler there is a utility called SDKLST. For example to generate a listview for the program SDKBTC simply load a Net Express command prompt, change to the \RND60\SOURCE directory and type 'SDKLST SDKBTC'. This will generate a program called \RND60\SOURCE\BINSRC\SDKBTCLV.CBL. When you compile using 'COMPILE SDKBTC' this will automatically compile the appropriate listview.

If you look at the source code generated you will see that there are new copybooks called LISTVW?.WRK. These provide the main sections of the listview program and allow a simple change to the copybooks, together with a recompile, to be able to add future functionality without having to ever regenerate the source code again. See User Controls - Adding Listviews/Toolbars.

See the topic Customizable Listviews for more information about applying the customization.

And toolbars...

There is an equivalent program for toolbars called SDKTBR. For example run 'SDKTBR SDKBTC' to generate \RND60\SOURCE\BINSRC\SDKBTCTB.CBL.

SYSPRO executable search paths have changed

Until now the SYSPRO executables have been built using a setting that causes the executable to search the registry for the Net Express run-time support files (mainly DLL's). This can cause a problem when Net Express has already been installed on the computer and the version is older or newer than that required for SYSPRO.

From SYSPRO 6.0 issue 007 the executables (IMPACT.EXE, IMPCSU.EXE, IMPCSC.EXE etc) have been built with the 'Shared (not dynamic)' settings. They will look for the Net Express run-time system in the base folder. This means that SYSPRO will no longer look in the registry for the location of the Net Express run-time support files.

e.net solutions business objects

e.net solutions has been developed rapidly since issue 006. There are now dozens of business objects that handle queries into the SYSPRO system. Many of these provide extensive query capabilities into the appropriate module.

In addition there has been an emphasis on developing Transaction.Post business objects. These include posting sales orders, purchase orders, inventory movements, requisitions, invoices and jobs transactions.

Now that e.net solutions has been available for over a year there have been many successful implementations in a large number of customer sites. Developers have already used applications developed in VB, VB.NET, ASP 3.0, ASP.NET and Delphi to invoke e.net business objects - including standalone and web based applications using COM, DCOM and COM+.

See the latest e.net business object library on the Suport Zone at www.syspro.com for more extensive documentation.

See also

SYSPRO 6.0 issue 007 database changes, sample programs, User Controls - Adding Listviews/Toolbars, Customizable Listviews, e.net solutions, business objects, Transaction.Post


What's new about SYSPRO 6.0 issue 006

As always each new issue of software has many new features and SYSPRO 6.0 issue 006 is no exception. For a complete and up-to-date list of features see the Support Zone at www.syspro.com.

Information for developers

Important - some changes to the SYSPRO 6.0 database have been made. If you have previously developed SYSPRO applications then see the topic SYSPRO 6.0 issue 006 database changes. In particular note that the A/P Supplier Master file has a new alternate index. If you are developing code for C-ISAM based systems that access APSMST you will need to recompile them before using them with SYSPRO 6.0 issue 006.

e.net solutions developers need not worry about changes to the SYSPRO 6.0 database as the business objects handle the changes.

SYSPRO source code samples

The SYSPRO 6.0 Software Development Kit has a few more Source code sample programs to help developers see how to use a standard function or use a programming technique. Download the latest SDK ZIP file and see the programs called SDK*.CBL.

Compiling SYSPRO programs

When SYSPRO 6.0 programs are compiled using the COMPILE.BAT batch file the screenset copybook (.CPB) is edited to change the screenset prefix to D-. For example when you generate the copybook for screenset SDK001.GS all fields are prefixed with SDK001-. When you compile SDK001.CBL the batch file edits these field prefixes and replaces then with a D- prefix.

From SYSPRO 6.0 issue 006 onwards the program that edits the data block (SDKCPB.EXE) has been enhanced to verify that the standard data block required by standard SYSPRO programs is 100% correct. You may find that some invalid data blocks are highlighted when you first compile them with issue 006. To correct the problem ensure that the standard data block is exactly the same as SDK001.CPB.

The reason that we have done this is that some standard functions will fail to work correctly unless the standard data block is correct.

e.net solutions business objects

e.net solutions now contains over 50 business objects. These have already been used successfully in a large number of customer sites. Developers have already used applications developed in VB, VB.NET, ASP 3.0, ASP.NET and Delphi to invoke e.net business objects - including standalone and web based applications using COM, DCOM and COM+.

See also

SYSPRO 6.0 issue 006 database changes, sample programs, e.net solutions, business objects


What's new about SYSPRO 6.0

SYSPRO 6.0 is the latest product developed from the rich features and functionality of IMPACT Encore 5.1.

The name IMPACT Encore has been re-branded to SYSPRO (note all uppercase) - in addition, we have kept the issue numbers running sequentially - thus Encore 5.1 issue 004 has become SYSPRO 6.0 issue 005.

To a large extent, then, SYSPRO 6.0 is simply the next issue of IMPACT Encore 5.1.

So are there any changes (apart from the name and internal version number)?

Good question...

As always each new issue of software has many new features added and SYSPRO 6.0 issue 005 is no exception. For a more complete and up-to-date list of features see the Support Zone at www.syspro.com for more details.

In addition, from a developers perspective...

We have renamed our internal development directories from \rnd51 to \rnd60. You will find that the SDK ZIP file contains these new naming conventions. Also note that \rnd51\prg51 has been renamed to \rnd60\prg (not prg60).

Also we have made a few changes to the data structures:

1. The Material allocation line number has changed from numeric to alphanumeric

2. The Counter sales deposit table has a new alternate index

3. There are several new fields in existing files and new tables. The script ISSUE005.SQL details these.

Other changes are

  • Reference to IMPACT, Encore or IMPACT Encore has been replaced with SYSPRO (all capitals). Note however that we have not change the names of the main executables or DLL's to ease the migration. Thus we still use IMPACT.EXE and Encore.DLL.

  • The internal system version number has been changed to 6.0 – detail program versions have been retained internally - they have not all been reset back to 000.

  • The listview user-control programs (??????LV.CBL) require an extra two lines to be added to the class-control. These lines are:

    • ExceptMgr is class 'exptnmgr'

    • OleExceptMgr is class 'oleexpt'

  • We have discovered an error in the Unix compilation batch file – COMPUNIX.BAT supplied as part of the SDK. This has a line that reads:

    • set cobcpy=..;..\copy51;..\..\gui;%impdir%

    • The copy51 should be copy60 – If this is wrong in your version please change it before using the batch file.

    • This has been corrected in SYSPRO 6.0 issue 006.

Unless your programs access the two above mentioned tables your existing custom programs will work without being recompiled. However, over time, it is recommended to use the latest copybooks provided in the SDK ZIP as many improvements have been made.

Note the initial release of SYSPRO 6.0 (Issue 005) used SYS60SDK.EXE - You may receive an Insufficient memory error when running this self-extracting zip so we have supplied a new one on the Support Zone at www.syspro.com. For more details see Installing the SYSPRO 6.0 SDK.

Also note that in late March 2003 SYSPRO 6.0 issue 006 has been released. This has corrected the problems mentioned above. It has a number of changes to the SYSPRO database. See the topic What's new about SYSPRO 6.0 issue 006.

The main new features of SYSPRO 6.0 are:

e.net Web-based Applications

Encore 5.1 issue 004 contained the first release of e.net solutions. This provided an object-model for developers to access the rich functionality of Encore 5.1 via a COM interface. SYSPRO 6.0 issue 005 now contains e.net Web-based Applications. These are a set of applications that can be run on a web browser. They are designed using the Microsoft .NET architecture and are based on the e.net COM objects previously released. Note that SYSPRO 6.0 issue 006 contains the Document Flow Manager.

Report Writer outputting XML

The Report Writer can now be configured to output XML (either 'raw' XML or together with a stylesheet to provide a browser interface to your reports). This feature allows your reports to be published in an intranet/internet environment. A Report Writer e.net business object called REPQRY that conforms to the Query.Query object model allows you to run XML enabled reports from your e.net solutions system. The Report Writer has a number of other new features for SYSPRO 6.0.

New Point of Sales System

SYSPRO 6.0 includes a streamlined Point of Sales system. This is similar to the Counter sales environment but has been optimized for a Point of Sale environment.

Distribution documents Word enabled

The documents printed from the distribution modules now allow Word printing functionality - these include: Invoices, Delivery notes, Order acknowledgements, Purchase orders, Inventory and Inspection documents.

Business Analytics

This is a new system that provides business analysis of financial, distribution and manufacturing data using OLAP technology.

Customer Relationship Management

This CRM system allows you to build better relationships with your customers.

Advanced Planning

There are 4 new modules that provide Finite Capacity Scheduling, Factory Planning, Progress Tracking and Quality Monitoring.

In addition there are many more detailed features - see www.syspro.com for a complete list.

See also

e.net overview, www.syspro.com, What's new about SYSPRO 6.0 issue 006, What's new about SYSPRO 6.0 issue 007, What's new about SYSPRO 6.0 issue 008


Module Naming Conventions

SYSPRO is built to be modular. There are a number of modules that may be licensed for a specific SYSPRO company. Each module has a standard (3 character) module code that is used to prefix program and/or data file names.

The text file IMPMOD.IMP that is shipped in the SYSPRO program directory contains the latest up-to-date list of modules. See the following examples.

Program name prefixes

Module code | Module description
IMP | System Admin & Shared Programs
APS | Accounts Payable
ARS | Accounts Receivable
CSH | Cash Book
GEN | General Ledger
INV | Inventory Control
POR | Purchase Orders
LCT | Landed Cost Tracking
SAL | Sales Analysis
WIP | Work in Progress
PRJ | Projects and Contracts
SOR | Sales Orders
BSO | Blanket S/o & Releases
QOT | Quotations
INT | Interface System
EDI | Electronic Data Interchange
MRP | Material Requirements Planning
STP | ST-Point Interface
ASS | Assets Register
BOM | Bill of Materials
ABC | Activity Based Costing
LOT | Lot Traceability
REP | Report Writer
COM | Object Libraries
C50 | Conversion Utilities from 4.0
DDS | Data Dictionary
SDK | Software Development Kit

Data file name prefixes

Module code | Module description | Table prefix
ADM | System Administration | Adm
TBL | System Tables | Tbl
APS | Accounts Payable | Ap
ARS | Accounts Receivable | Ar
CSH | Cash Book | Csh
GEN | General Ledger | Gen
INV | Inventory Control | Inv
CFG | Product Configurator | Cfg
POR | Purchase Orders | Por
REQ | Requisitions | Req
GRN | GRN Suspense | Grn
LCT | Landed Cost Tracking | Lct
GTR | Goods in Transit | Gtr
BPO | Blanket Purchase Orders | Bpo
SAL | Sales Analysis | Sal
WIP | Work in Progress | Wip
PRJ | Projects and Contracts | Prj
SOR | Sales Orders | Sor
MDN | Multiple Delivery Notes | Mdn
POS | Counter Sales | Pos
BSO | Blanket S/o & Releases | Bso
QOT | Quotations | Qot
INT | Interface System | Int
EDI | Electronic Data Interchange | Edi
MRP | Material Requirements Planning | Mrp
STP | ST-Point Interface | Stp
ASS | Assets Register | Asset
BOM | Bill of Materials | Bom
ABC | Activity Based Costing | Abc
LOT | Lot Traceability | Lot
ECC | Engineering Change Control | Ecc
ARC | Archive System | Arc
REP | Report Writer | Rep
DDS | Data Dictionary | Dds

See also

IMPMOD.IMP


Source code samples

SYSPRO SDK

Source Code Samples

SYSPRO 6.1 Sample Programs

Introduction

The Software Development Kit is shipped with a number of sample source code files and programs. The programs have been provided to demonstrate various development techniques.

The sample program SDK001 should be used as an introduction to generic SYSPRO programs. Follow the link to SDK001 for a walk through of the common elements of a SYSPRO program and associated screenset. The remainder of the source code samples are designed to be self documenting and typically demonstrate one or more of the functions defined in this SDK documentation.

Program | Description | Notes
SDK001 | Basic sample program | Shows a simple Dialog application
SDK002 | Basic listview program | Shows using a limitless listview
SDK003 | Basic toolbar program | Shows using a listview and toolbar
SDK004 | How to use Data Objects | Shows how to use Net Express Data Objects
SDK005 | Docking Panes | Shows how to code Docking panes, Toolbar, RTF and Image viewer objects
SDK006 | Listview | Same as SDK005 plus limitless Listview
SDK007 | Display Form | Same as SDK006 plus Display Form
SDK008 | Entry Form | Same as SDK007 plus Entry Form
SDK009 | Assign Lists and Checkboxes | Shows how to use LIST.PRO/LIST.WRK allowing you to assign items from a list of available ones.
SDK010 | Invoke SRS report with XML | Shows how to pass your own XML directly to an SRS report
SDK016 | Skeleton for training | Skeleton program to be used as part of developers learning - See SDK016.DOC for sample task
SDKAPI | Show Windows API calls | Demonstrates how to call the Win32 API
SDKBFI | Show File/Folder browsing | Demonstrate the S-FILE-BRW function
SDKBIG | Creates large ISAM files | Creates very large C-ISAM files for testing limits
SDKBIN | Used to edit user-controls | See the Screen Customization Kit - A worked example
SDKBLG | Language code browse | Simple browse on language codes
SDKBTC | Terms code browse | Browse on Terms codes using BROWSE.PRO. Also demonstrates use of a SQL Timestamp.
SDKCB1 | Call ARSQRY | Call ARSQRY - Get Single Element - CALL-BO-QUERY
SDKCB2 | Call ARSQRY | Call ARSQRY - Parse XmlOut - CALL-BO-QUERY
SDKCB3 | Call ARSSCS | Call ARSSCS - Add, Update, Delete Customer CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE
SDKCB4 | Call SORRSH | Call SORRSH - Build Sales Order - CALL-BO-BUILD
SDKCB5 | Call SORTOI | Call SORTOI - Add Sales Order - CALL-BO-POST
SDKCB6 | Open and Parse XML file | How to open a physical XML disk file and parse it using the SYSPRO XML parser (COMPAR)
SDKCPB | Compile edit CPB | Compile utility to edit CPB and validate data block. Typically only use prepared executable SDKCPB.EXE
SDKDAT | Increment company dates | Utility to increment demo company dates
SDKDCV | Convert codes for demo | Utility to convert G/L, Customer, Supplier keys
SDKDIF | File byte comparison | Compares two files for an exact byte match
SDKDLY | Simple executable | Demonstrates creating a simple executable. This example provides an x second delay.
SDKEDT | Entry Forms | Demonstrates some basic and more advanced use of Entry Forms for SYSPRO 6.0 issue 010 onwards
SDKERR | Invoke error program | A test harness for simulating various types of errors and their messages.
SDKFND | Find string in file | Finds strings in file – simple grep
SDKGRP | Sample graphic program | Demonstrate use of standard graph functions
SDKHEX | ASCII/HEX/GUID conversion | Demonstrates how to convert between ASCII and Hex and between GUID16 and GUID38 formats. CONVERT-ASCII-TO-HEX CONVERT-HEX-TO-ASCII CONVERT-GUID16-TO-GUID38 CONVERT-GUID38-TO-GUID16
SDKLCK | Resourc Locking | Resource Locking test harness.
SDKLNG | Language Translate | System to assist with Language Translation
SDKLOG | Output debugging log | Utility to assist with debugging. See OUTPUT-DEBUG-LOG
SDKLOW | Source code to lower case | Utility to allow you to convert source code to lower case
SDKLST | Create Listview Utility | Utility to create listview source code
SDKMSG | Message Box example | Demonstrates using INVOKE-MESSAGE-BOX and INVOKE-TASK-DIALOG.
SDKP25 | SQL Optimized report | Legacy Inventory valuation report with SQL optimization logic
SDKPAT | Pattern Matching | Demonstrates wildcard pattern matching in PROFIND.PRO
SDKPER | PIC type performance | Compares Net Express PIC types for performance
SDKQRY | AR Query | Simplified version of very old format AR Query
SDKREP | Call Report Writer | Demonstrates running a R/W report with parameters. See the topic Printing using the Report Writer.
SDKRPT | Show listview and grids | Shows many examples of how to use listviews, grid controls, tree views etc. Also helps you to understand the various callouts and returned parameters.
SDKRUN | Run e.net business object | Sample e.net business object for Utilities.Run method
SDKSE2 | SQL performance CMS | Compares SQL performance Uses ArCustomer and CmsContact tables
SDKSEL | SQL performance Inventory | Compares SQL performance with parameters Uses the InvMaster and InvWarehouse tables
SDKSIG | eSignature Test Harness | Demonstrates code you would insert to prepare and test for eSignatures.
SDKSQL | OpenESQL sample | Demonstrates using OpenESQL in program. Contains EXEC SQL statements being used in source code.
SDKSQM | ISAM - SQL converter | Demonstrates calling IMPSQM to migrate data between SQL/ISAM
SDKTBR | Create Toolbar Utility | Utility to create toolbar source code
SDKTHL | Thai copyright sample | Program for use in Thailand
SDKTRG | Trigger example | Shows how to write a trigger program. i.e. a program that can be invoked from a SYSPRO Trigger.
SDKTRN | Transaction processing | Demonstrates SQL Server Transaction Processing BEGIN-TRANSACTION, COMMIT-TRANSACTION
SDKTRU | True/False evaluation | Demonstrates PROCESS-WW-LOGIC-TAB. This can be used as part of an application to evaluate complex logic.
SDKUPD | SQL Optimized update | Demonstrates Optimized SQL updates
SDKUPP | Converts file names | Utility to convert file names to upper/lower case. Can also be used to detect for file names in lower-case.
SDKUPR | Front end to GENUPR | Utility to supply input to GENUPR and display results
SDKVER | Invert version comments | Utility to invert sequence of version comments in source code. Used internally by SYSPRO development for SYSPRO 6.1.
SDKWSH | File and Folder functions | Various file and folder functions such as S-OSGETD
Remarks

Syspro continually develop and enhance their sample programs to demonstrate various programming techniques. Always use the latest software development kit to see the latest samples. This is available in the Developers section of the Support Zone at www.syspro.com.

Please note that these programs are provided 'as is' and have not been through the usual SYSPRO testing process nor are they intended to perform any specific business function. They are intended to demonstrate various programming techniques and should be used for this purpose only.

See also

Source SDK001 Overview, Screen customization worked example, OUTPUT-DEBUG-LOG, INVOKE-MESSAGE-BOX, business object, Utilities.Run, Comment header block for SYSPRO programs, Comment header block for e.net programs, LIST.PRO


Source SDK001 Overview

SYSPRO SDK

Source Code Samples

Sample Program Overview SDK001

The program SDK001.CBL is a basic sample program that demonstrates many of the techniques required for a typical SYSPRO program. This program is designed to prompt the operator for a stock code and to show it's description and mass. There is a browse to allow a stock code selection to be made. To run it from the SYSPRO main menu use File, Run, SDK001 or add SDK001 to your Favorites menu.

There is a similar sample program (SDKCB1) that asks a customer and shows it's name - it demonstrates how to call a business object to retrieve this information rather than accessing the SYSPRO database directly.

Once you have installed the SYSPRO Software Development Kit (see Setting up a Development Environment) you will find the relevant source code as follows:

\rnd60\source\SDK001.CBL | Program source code
\rnd60\gui\SDK001.GS | Screenset
\rnd60\gui\SDK001.CPB | Data block copybook

The remainder of this document is divided into the following topics:

  • The source code structure

  • The dialog system

Source code structure

This program is a typical SYSPRO program that has standard elements. These are explained below. Note that the source code defines the business logic, in addition the source code calls the dialog system to provide any user-interface. The user-interface may be running on the same or a different computer in the case of a client/server system. The data block is used to pass information to and from the screenset.

Comment header block

The first few lines of every SYSPRO program consists of a comment header block. This is a consistent method of documenting the program name, description and other settings. See the example below.

Syspro use some proprietary utilities that read these comment blocks to create various databases – including the IMPPRG.IMP file.

For more information see Source comment header block. For information about developing an e.net business object see Comment header block for e.net programs.

**************************************************************

** SYSPRO **

** Copyright (c) 1994-2009 SYSPRO Ltd. All rights reserved.**

**************************************************************

** Program name : SDK001 **

** Description : SYSPRO SDK Basic SYSPRO Program **

** Run from menu : Yes **

** Can be secured: Yes **

** Owner : Core **

**************************************************************

* Date Init PDR Description

001 * 29/08/02 RJH 51649 SYSPRO 6.0 branding

000 * 05/09/01 JC 45626 Program copied to create Encore 5.1

*

* This program is designed to allow show the basics in

* creating an SYSPRO 6.0 program.

File definition

After the comment header block comes the file definition section. This defines the data files used by the program. See the example below. All standard SYSPRO files have a 6 character file code assigned, made up of a 3 character module code (such as INV for Inventory or SOR for Sales Orders) and a 3 character file description (such as MST for Master and DET for Detail).

Generally each file to be accessed requires a SELECT statement and a Record layout definition.

The SELECT statements for each of the standard SYSPRO files are defined in copybooks that have a SEL suffix.

The Record layouts for each of the standard SYSPRO files are defined in copybooks that have a MAC or MAI or MAS or MAT or MAM suffix. (i.e. MA?).

All programs must also use the standard printer definition file ADMREP as shown in the example below.

FILE-CONTROL.

*

COPY "INVMST.SEL". *> Inventory master SELECT copybook

COPY "ADMREP.SEL". *> Printer SELECT copybook

*

DATA DIVISION.

FILE SECTION.

*

FD INVMST.

COPY "INVMST.MAC". *> Inventory master record layout

*

FD ADMREP.

COPY "ADMREP.MAS". *> Report record layout

Note that if you have to define your own SELECT statement and your program may be run from a COM environment see the topic Developing for a COM environment.

Working storage section

After the file definition comes the working storage section. This is where you define all variables, constants and working fields to be used by your program. See the example below.

For consistency all standard SYSPRO programs have a WHAT-STRING defined as the first part of the working storage section. This is a string that defines the version. When compiled the special string @(#) even makes this string available in the compiled object code. The field VERS is a mandatory field defining the 3 digit program version.

Next comes the specific fields for each program. This is a free format area where you can define fields to be used, variables, constants, strings and any other type of data required by the program.

At the end of the working storage section are typically a number of standard copybooks. These copybooks define a whole host of common fields used by standard routines. In addition they define linkages required when calling other programs and when calling the screenset for your program. Note that SDK001.CPB is the name of the data block definition copybook.

WORKING-STORAGE SECTION.

01 WHAT-STRING VALUE "@(#) Program version .001".

03 FILLER PIC X(25).

03 VERS PIC 9(3).

01 WHAT-DUMMY PIC X(2) VALUE X"0D0A".

*

01 FIELD-1 PIC X(25).

* Dummy field

*

COPY "SDK001.CPB". *> Dialog system data block copybook

COPY "DSCTL.WRK". *> Dialog system control block

*

COPY "STANDARD.WRK". *> Common working storage copybook

COPY "WWLINK.WRK". *> Common IMPSTD copybook

COPY "LNK.WRK". *> Copy LINK copybook

01 LNK2 PIC X. *> Dummy 2nd linkage copybook

The linkage section

This section defines parameters that are passed to your program. Standard SYSPRO programs have a common linkage that is passed between all programs - this is defined in LINK.WRK. When using this standard linkage simply use the coding shown below. Note that there is a dummy linkage field called LINK2 that is generally unused. You should still include it as standard routines make reference to this field.

LINKAGE SECTION.

COPY "LINK.WRK". *> Standard linkage

01 LINK2 PIC X. *> Dummy 2nd linkage

Procedure division

The procedure division is where all the work actually happens. This is where the program starts. Whilst the scope of what can be done in the procedure division is large generally the program will perform the following basic steps.

  1. Run through PROBEGIN.PRO

  2. Build and open any files required

  3. Initialise any field required

  4. Call a screenset to allow the user to make selections or perform actions

  5. Handle the functions required by the user

  6. Shutdown gracefully, closing files, removing Windows left behind, returning to the calling program or menu

Remember that the sample program is designed to prompt the operator for a stock code and to show it's description and mass. There is a browse to allow a stock code selection to be made.

Initialization

Generally immediately after the PROCEDURE DIVISION statement you should use the PROBEGIN.PRO copybook. This copybook defines many functions that are commonly used by SYSPRO programs. See Functions by name and Functions by type for a full list of the available functions. Next the sample program builds and opens the files used and then initializes the screenset data block and control block. See below.

PROCEDURE DIVISION USING LINK, LINK2.

COPY "PROBEGIN.PRO".

*

** Build and open files

PERFORM INVMST-BUILD-AND-OPEN-IO.

PERFORM COMER.

*

** Initialize dialog system fields

INITIALIZE DS-CONTROL-BLOCK.

INITIALIZE D-DATA-BLOCK.

MOVE "SDK001" TO SCREENSET-NAME.

MOVE DSG-PUSH-SET TO DSG-CONTROL.

Event loop

Next the program will typically call the screenset and wait for the operator to respond. This is the task of the event loop. This consists of a simple loop, calling the screenset, detecting the actions required, performing the actions and returning for any other events. The event loop in the sample program is shown below.

************************************************

** Main Dialog system message handling loop **

************************************************

MAIN-DS-LOOP.

PERFORM CALL-DS.

*

IF D-S-FR-MSG = "read"

PERFORM READ-ROUTINE.

*

GO TO MAIN-DS-LOOP.

Main program functions

The functions to be performed by most programs are called from the event loop. In our example this is where we are going to read the stock code and return the data to the screenset. To read a record from the Inventory Master file (file code INVMST) is simply a case of moving the stock code to the key (INVMST-KEY) and using the standard routine INVMST-READ. This will return a status that can be used to determine success. On a successful read the fields in the record layout defined by INVMST.MAC are valid and can be used. In this case the fields are moved to the screenset data block fields.

**********************************************************

** Read stock code and return description etc **

** Input : D-STOCK-CODE Stock code **

** Output : D-DESCRIPTION Description **

** D-MASS Mass **

**********************************************************

READ-ROUTINE.

MOVE SPACES TO INVMST-KEY.

MOVE D-STOCK-CODE TO INVMST-STK.

PERFORM INVMST-READ.

IF STAT-OK

MOVE INVMST-DESC TO D-DESCRIPTION

MOVE INVMST-MASS TO D-MASS

ELSE

MOVE "{Not found}" TO D-DESCRIPTION

MOVE ZERO TO D-MASS.

Shutdown

The final process is to close the program gracefully. This is defined by the ENDJOB routine. Generally the ENDJOB routine will close any open files, exit the dialog system and use the EXIT PROGRAM statement to return control to the calling program or menu.

Note that the screenset can branch to this ENDJOB routine by using a S-EXIT function without the application having to have specific coding to handle this. Because of this the ENDJOB function is mandatory for all SYSPRO programs.

In addition the CANCELREQ, HOF and REGISTER-MESSAGES are also mandatory. These can be null routines if not required. See below.

**************

** Endjob **

**************

CANCELREQ.

REGISTER-MESSAGES.

HOF.

ENDJOB.

PERFORM CLOSE-ALL-FILES.

PERFORM QUIT-DS.

EXIT PROGRAM.

Dialog system

The Dialog system is designed to allow a programmer to quickly and effectively define a user-interface for a program. The user-interface is saved as a screenset. The screenset can interact with the operator showing data on the screen or returning data and messages back to the calling program. The screenset data block is used to pass information between the source code and the screenset.

The screenset is edited using the Dialog system. This is part of the Net Express development system. A screenset is a file that has a .GS extension - this indicates that the screenset is editable. When shipping the finished screenset this can be stored in a read-only format with a .RS extension. Remember to keep the original .GS version.

A screenset consists of three main parts

  • The data block. This defines the data to be passed between the screenset and the calling program

  • The screen painter. This defines the windows, dialog boxes and the objects that reside on them. It defines the position, size and color of each object together with any associated text.

  • The Dialog. This is a simple language that allows the programmer to determine the events to be trapped and the actions to performed when the events occur. The Dialog also controls the interaction with the calling program.

Data block

To provide a number of standard and consistent functions SYSPRO screensets have a data block that must start with standard fields. All of these fields begin with S-. The first must be S-FR-MSG. It is important to include all the standard fields unchanged in any way. The screenset SDK001.GS contains these fields.

In addition, the very last field in the data block must be the field S-END, this is used by standard mapped and client/server routines to verify the correctness of the data block.

After the standard data block fields (but before the S-END field) you may define your own data block fields. In the sample program we need to define a stock code, stock description and the mass. These are defined (just before the S-END field) as shown below. The total data block size must not exceed 64000 bytes.

* User-defined fields in data block

* ---------------------------------

STOCK-CODE X 30.0

*

DESCRIPTION X 30.0

*

MASS 9 6.6

*

S-END X 3.0

Once you have finished editing the data block you should create the screenset data block copybook. This is a copybook definition of the data block that is to be incorporated into your source code (SDK001.CPB in our example). Use File, Generate, Datablock copyfile…

Dialog

To provide a number of standard and consistent functions each screenset has some standard dialog. This is used to trap the common events such as F1, F8, Shift+F2 through Shift+F8 etc in addition to simplify coding for common functions.

When the screenset is first called by a program (using the PERFORM CALL-DS function) the SCREENSET-INITIALIZED event is triggered against the screenset's global dialog. This allows you to initialise any fields and to perform any initialisation coding and should finally set the focus on the first object.

When a screenset wishes to return control to the calling program the RETC function should be used. This is typically preceded by an action being passed into S-FR-MSG. For example to exit the program the dialog would be:

MOVE "S-EXIT" S-FR-MSG

RETC

It would then be the program's responsibility to check the field D-S-FR-MSG to determine the action to be performed. Remember that functions beginning with S- are reserved for standard SYSPRO functions and do not have to be defined in your program.

Also note that in your Net Express program the data block fields are prefixed with D- where as in the screenset the fields are not prefixed with D-.

Reading the stock code

For example when the operator clicks on the Read push button this is detected against the push button as a BUTTON-SELECTED event which then performs the following READ-PROC function in global dialog.

READ-PROC

MOVE "read" S-FR-MSG

RETC

REFRESH-OBJECT WIN-MAIN

SET-FOCUS EF-STOCK-CODE

The RETC causes the program to return to the calling program. The source code then checks D-S-FR-MSG for the value 'read' (exact case). This then reads the stock code and then performs CALL-DS again. This causes control to pass back to the screenset (immediately after the RETC) where the screen is refreshed (causing the data block fields that have changed to be refreshed on the window) and focus is reset back to the stock code entry field.

Further reading

The above has demonstrated a typical, but simple, example of how a SYSPRO program works. It is suggested that you familiarize yourself with this functionality, including using Net Express Animator to step through the source code. See Setting up a SYSPRO 6.0 Development Environment if you have not already done so. You can then do the same with the other Source code samples supplied as part of the SYSPRO SDK.

A thorough understanding of the standard functions available in PROBEGIN.PRO and the standard functions available from the Dialog system will allow you to develop sophisticated custom applications.

See also

Source code samples, Functions by name, Functions by type, Dialog functions by name, Dialog functions by type, Setting up a SYSPRO 6.0 Development Environment, Comment header block for e.net programs, Calling Business Objects Sample Program (SDKCB1), ENDJOB, PROBEGIN.PRO, WHAT-STRING,


Source comment header block

SYSPRO SDK

Source Code Samples

Comment header block

The first few lines of every SYSPRO program consists of a comment header block. This is a consistent method of documenting the program name, description and some other settings.

Syspro use some proprietary utilities that read these comment blocks to create various databases – including the IMPPRG.IMP file.

The template file STDHDR.TXT found in the source code directory can be used to ensure that the comment header uses the standard format. The following example is taken from the sample source code program SDK001.CBL.

**************************************************************

** SYSPRO **

** Copyright (c) 1994-2009 SYSPRO Ltd. All rights reserved.**

**************************************************************

** Program name : SDK001 **

** Description : SYSPRO SDK Basic SYSPRO Program **

** Run from menu : Yes **

** Can be secured: Yes **

** Owner : Core **

**************************************************************

* Date Init PDR Description

001 * 29/08/02 RJH 51649 SYSPRO 6.0 branding

000 * 05/09/01 JC 45626 Program copied to create Encore 5.1

*

* This program is designed to allow show the basics in

* creating a SYSPRO program.

The comment header consists of a number of areas – each of these is detailed below.

Program name

This is a 6 character name of the source file (without the .CBL extension). This is used when listing the file and has no other purpose.

Description

This is a 40 character program description. When using the USAGE60 utility this description will be used to create the program description in the IMPPRG.IMP file. Generally the description should be prefixed with an abbreviated module code. For example all Sample source code programs that are part of the SYSPRO Software Development Kit have their descriptions prefixed with SYSPRO SDK.

Using consistent naming helps to make the program description clearer when read out-of-context. Try to make the 40 character description meaningful so that end-users will understand the program purpose.

Run from menu

This is a flag indicating whether the program can be run from the menu (either using a menu shortcut or using the File, Run facility). If the program requires parameters to be passed for it to run successfully then use the keyword No otherwise use Yes. This N and Y values relate to the column called Men in the IMPPRG.IMP file.

Can be secured

This is a flag indicating whether the program will appear in the list of programs when defining operator group level security. Generally it should be set to Yes however if the program is a utility program that should always be available then set this to No. If you set this to No then you must also add the line MOVE "N" TO CHECK-ACCESS immediately below the PROCEDURE DIVISION (Before any other source lines). The Y and N values relate to the column called Sec in the IMPPRG.IMP file.

Browse

This is a flag that can be used to override whether the program is a browse program or not.

The utility that SYSPRO use to determine browse programs looks for the existence of the copybook BROWSE.PRO. When BROWSE.PRO exists a B is moved to the appropriate column in the IMPPRG.IMP file.

This allows an administrator to configure program access as Allowed, Denied or Browse only.

Note that in the vast majority of programs the existence/absence of BROWSE.PRO correctly indicates whether the program is a browse or not. However there are some exceptions.

Programs that are exceptions can have a 'Browse' comment set to Yes or No to override this automatic browse determination.

For example:

** Browse : Yes **

Owner

This field is only used internally by Syspro. It describes the department that is responsible for the development and maintenance of the program. Current valid choices are:

Core

Financial

Distribution

Manufacturing

Nationality

This is an optional field and is not used in most standard SYSPRO programs. It indicates whether the program should only be available when running in a specific nationality. Generally you should not need to specify this line. If you only want the program to appear in the list of programs (say against the File, Run function) when using a specific nationality (defined in the System Setup) then you should define the 3 character nationality code (e.g. USA) against this entry. The keyword defined here relates to the Nat column in the IMPPRG.IMP file.

Version control block

The last part of the comment header block is a version control block.

The version control block is at used Syspro to cross-reference the version number of the program with the event number being used to enhance/correct the program and the programmer who made the change. This allows a quick check of the work that has been done on the program since it was developed.

This version control block contains a three digit version number, date of modification (DD/MM/YY), Initials of programmer changing the source code, the event number (PDR) and a short description of the change made. The description can continue over several lines if required. See the following example:

*

* Date Init PDR Description

001 * 29/08/02 RJH 51649 SYSPRO 6.0 branding

000 * 05/09/01 JC 45626 Program copied to create Encore 5.1

Each line of source code added or changed with this event will be have the program version number (001 in this case) inserted as the first 3 characters.

Note that whilst the program version is being developed at SYSPRO the program version will also have !!! added to indicate that the program is under-development. For example the line above would look like:

* Date Init PDR Description

001!!!* 29/08/02 RJH 51649 SYSPRO 6.0 branding

000 * 05/09/01 JC 45626 Program copied to create Encore 5.1

Once it is 'signed-off' by a tester the !!! will be removed and the program will be made generally available. You may see some SDK sample code with '!!!' when we ship sample programs that are still under development.

Other comments

Depending on the program, programmers often add additional comments below the version control block and before the first line of code indicating the program usage, any parameters required or other features or limitations to assist future maintenance.

See also

Basic sample program (SDK001), IMPPRG.IMP, Comment header block for e.net programs


Comment header block for e.net

SYSPRO SDK

Source Code Samples

Comment header block for e.net programs

The first few lines of every e.net business object program consists of a comment header block. This is a consistent method of documenting the program name, description and some other settings.

Syspro use some proprietary utilities that read these comment blocks to create various databases – including the IMPPRG.IMP file.

The template file STDHDR.TXT found in the source code directory can be used to ensure that the comment header uses the standard format. The following example is taken from the sample source code program SDKRUN.CBL.

$set REENTRANT(2)

$set CONSTANT REENTRANT-DIRECTIVE(2)

**************************************************************

** SYSPRO **

** Copyright (c) 1994-2009 SYSPRO Ltd. All rights reserved.**

**************************************************************

** Program name : SDKRUN **

** Description : SYSPRO SDK Generic e.net Run Program **

** Run from menu : Business Object Utility **

** Can be secured: Yes **

** Owner : Core **

**************************************************************

*

* Date Init PDR Description

002 * 29/08/02 RJH 51649 SYSPRO 6.0 branding

001 * 20/06/02 RJH 49887 Define ProgramId

000 * 05/02/02 RJH 45525 New program for Encore 5.1 and e.net

*

* This program is designed to be used from e.net using the

* Utilities.Run method

The comment header consists of a number of areas – each of these is detailed below.

Directives (beginning $set)

When running any business object in a COM environment it is critical that the business object (and all programs called by the business object) are compiled with the $set REENTRANT(2) directive. To assist in diagnosing programs that do not have this directive you should also define a constant called REENTRANT-DIRECTIVE as shown above. The constant will be verified at run-time and, if missing, an appropriate exception will be raised.

Note that from SYSPRO 6.1 onwards the REENTRANT(2) directive has been set by default and therefore neither of these two directives are required.

Program name

This is a 6 character name of the source file (without the .CBL extension). This is used when listing the file and has no other purpose.

Description

This is a 40 character program description. When using the USAGE60 utility this description will be used to create the program description in the IMPPRG.IMP file. Generally the description should be prefixed with an abbreviated module code. For example all Sample source code programs that are part of the SYSPRO Software Development Kit have their descriptions prefixed with SYSPRO SDK.

Using consistent naming helps to make the program description clearer when read out-of-context. Try to make the 40 character description meaningful so that end-users will understand the program purpose.

Generally capitalize each word in the description.

Run from menu

For e.net business objects this indicates the type of business object. Valid values are:

- Business Object Utility

- Business Object Query

- Business Object Transaction Posting

- Business Object Retrieve

- Business Object Setup

A flag representing the value of this field will be stored in the IMPPRG.IMP file under the Men heading.

A special value of 'Component' - i.e. 'Run from menu : Component' indicates that this is a special program that does not take XML as input or return XML.

Can be secured

This is a flag indicating whether the program will appear in the list of programs when defining operator group level security. Generally it should be set to Yes however if the program is a utility program that should always be available then set this to No. If you set this to No then you must also add the line MOVE "N" TO CHECK-ACCESS immediately below the PROCEDURE DIVISION (Before any other source lines). The Y and N values relate to the column called Sec in the IMPPRG.IMP file.

Owner

This field is only used internally by Syspro. It describes the department that is responsible for the development and maintenance of the program. Current valid choices are:

Core

Financial

Distribution

Manufacturing

Version control block

The last part of the comment header block is a version control block.

The version control block is at used Syspro to cross-reference the version number of the program with the event number being used to enhance/correct the program and the programmer who made the change. This allows a quick check of the work that has been done on the program since it was developed.

This version control block contains a three digit version number, date of modification (DD/MM/YY), Initials of programmer changing the source code, the event number (PDR) and a short description of the change made. The description can continue over several lines if required. See the following example:

*

* Date Init PDR Description

002 * 29/08/02 RJH 51649 SYSPRO 6.0 branding

001 * 20/06/02 RJH 49887 Define ProgramId

000 * 05/02/02 RJH 45525 New program for Encore 5.1 and e.net

Each line of source code added or changed with this event will be have the program version number inserted as the first 3 characters.

Note that whilst the program version is being developed the program version will also have !!! added to indicate that the program is under-development. For example when changing the program for new version 002 the comments would look like:

* Date Init PDR Description

002!!!* 29/08/02 RJH 51649 SYSPRO 6.0 branding

001 * 20/06/02 RJH 49887 Define ProgramId

000 * 05/02/02 RJH 45525 New program for Encore 5.1 and e.net

Once it is 'signed-off' by a tester the !!! will be removed and the program will be made generally available.

Other comments

Depending on the program, programmers often add additional comments below the version control block and before the first line of code indicating the program usage, any parameters required or other features or limitations to assist future maintenance.

See also

Developing for a COM Environment, IMPPRG.IMP, Comment header block for SYSPRO programs


ENDJOB

SYSPRO SDK

Source Code Samples

ENDJOB Definition

The final process in a SYSPRO program is to close gracefully. This is defined by the ENDJOB routine. Generally the ENDJOB routine will close any open files, close any printer file, exit the dialog system and use the EXIT PROGRAM statement to return control to the calling program or menu.

Note that the screenset can branch to this ENDJOB routine by using a S-EXIT function without the application having to have specific coding to handle this. Because of this the ENDJOB function is mandatory for all SYSPRO programs.

Also note that if an operator has been denied access to a program the PROBEGIN.PRO copybook may immediately branch to ENDJOB so any code in this paragraph must have already been initialized.

It is highly recommended that any other functions that are performed in ENDJOB are only performed when appropriate. For example if your ENDJOB routine deletes a temporary file that could have been created during the run of the program then only delete the file when a flag is set indicating that the temporary file was created.

In addition the CANCELREQ, HOF and REGISTER-MESSAGES are also mandatory. These can be null routines if not required. See below for a typical ENDJOB.

**************

** Endjob **

**************

CANCELREQ.

REGISTER-MESSAGES.

HOF.

ENDJOB.

PERFORM CLOSE-ALL-FILES.

PERFORM QUIT-DS.

EXIT PROGRAM.

See also

Source code samples, Functions by name, Functions by type, PROBEGIN.PRO


WHAT-STRING

SYSPRO SDK

Source Code Samples

WHAT-STRING Definition

For consistency all standard SYSPRO programs have a WHAT-STRING defined as the first part of the WORKING-STORAGE section. This is a string that defines the program version.

When compiled the special string @(#) even makes this string available in the compiled object code using an appropriate utility (such as the Unix 'what' command). Note that the copybook STANDARD.WRK also has a what string defining the system version.

The field VERS is a mandatory field as it is referenced by PROBEGIN.PRO. It defines the 3 digit program version.

See the following example WHAT-STRING with a program version '001'.

WORKING-STORAGE SECTION.

01 WHAT-STRING VALUE "@(#) Program version .001".

03 FILLER PIC X(25).

03 VERS PIC 9(3).

01 WHAT-DUMMY PIC X(2) VALUE X"0D0A".

See also

Source code samples, Functions by name, Functions by type, PROBEGIN.PRO


PROBEGIN.PRO

SYSPRO SDK

Source Code Samples

PROBEGIN.PRO Definition

The PROBEGIN.PRO copybook should be included in your source code immediately after the PROCEDURE DIVISION statement.

PROBEGIN.PRO contains many functions that are commonly used by SYSPRO programs. See Functions by name and Functions by type for a full list of the available functions.

PROBEGIN.PRO is designed to be executed as one of the first statements in your code. It initializes several fields, sets up the program version, tests the program security and starts the job logging. You should not bypass execution of the initialization functions in this copybook.

The following is a code fragment from the sample program SDK001 showing typical placement of PROBEGIN.PRO.

PROCEDURE DIVISION USING LINK, LINK2.

COPY "PROBEGIN.PRO".

Important

Part of the logic in PROBEGIN.PRO verifies the program security. If the operator has been denied access to the program then an appropriate message is displayed and the logic immediately branches to ENDJOB. It is important that any initialization that ENDJOB may test for is setup before PROBEGIN.PRO.

If your program is always allowed to be run then you should disable the security checking in PROBEGIN.PRO by moving 'N' to the field CHECK-ACCESS. See the following example:

PROCEDURE DIVISION USING LINK, LINK2.

MOVE "N" TO CHECK-ACCESS.

COPY "PROBEGIN.PRO".

Important - You must not move "N" to CHECK-ACCESS unless your program can always be run. Once you have added this line of code your program cannot be secured by an administrator.

Mandatory paragraphs

PROBEGIN.PRO requires that the following paragraphs have been included in your source code:

CANCELREQ

REGISTER-MESSAGES

HOF

ENDJOB

Apart from ENDJOB the others can be null routines if not required. See below.

**************

** Endjob **

**************

CANCELREQ.

REGISTER-MESSAGES.

HOF.

ENDJOB.

PERFORM CLOSE-ALL-FILES.

PERFORM QUIT-DS.

EXIT PROGRAM.

See also

Source code samples, Functions by name, Functions by type, ENDJOB, Basic Sample program (SDK001), Calling Business Objects Sample Program (SDKCB1)


Calling Business Objects Overview

History of SYSPRO Componentization

SYSPRO applications were originally developed as monolithic programs containing many embedded functions.

Since the early 1990's many of the functions were separated out into smaller programs that could be called when required. This allowed SYSPRO developers to access common functionality without having to re-invent the code each time. The interfaces to these programs were often only tersely documented.

e.net Solutions was the next step in componentization of SYSPRO functionality. Launched in 2002 e.net Solutions consists of a number of business objects that can be called from COM enabled languages such as VB, VB.NET, C++, C# etc. Business objects accept input as XML strings and all output is returned as XML strings. This allows virtually any developer to access the rich SYSPRO business logic available. The XML is completely described using schemas to ensure complete openness and consistency.

The most recent part of the componentization process has been to re-engineer the existing SYSPRO application programs to call these business objects. This topic explains how this has been done and how you can change your SYSPRO applications to call business objects.

See the topics Advantages of Calling Business Objects and Licensing Implications when calling Business Objects for more information.

Audience

This topic is designed to allow Net Express developers to learn how to call business objects from within their Net Express programs.

If you are a developer using VB, VB.NET, C++, C# or any other COM enabled language then you should be calling e.net business objects using the e.net Object Model (and this topic is not designed for you).

Sample code

The Software Development Kit shipped with SYSPRO 6.1 onwards consists of several sample Net Express source code programs. These demonstrate the most common ways of accessing business objects. These programs are designed to be self-documenting so you can get up-and-running as soon as possible. The sample programs are shown in the following table.

The sample program SDKCB1 should be used as an introduction to developing SYSPRO programs that call business objects. Follow the link to SDKCB1 for a walk through of the common elements of a SYSPRO program that calls a business object.

Sample Program | Description | Notes
SDKCB1 | Call ARSQRY Get Single Element | Demonstrates calling the A/R Query business object using CALL-BO-QUERY and parsing the returned XML looking for a single element value
SDKCB2 | Call ARSQRY Parse XmlOut | Demonstrates calling the A/R Query business object using CALL-BO-QUERY and parsing the returned XML looking for multiple element values
SDKCB3 | Call ARSSCS Add,Chg,Del Customer | Demonstrates calling the A/R Setup business object using CALL-BO-ADD, CALL-BO-UPDATE and CALL-BO-DELETE to Add, Update and Delete customers.
SDKCB4 | Call SORRSH Build Sales Order | Demonstrates calling the S/O Build business object using CALL-BO-BUILD allowing information relating to a customer to be returned ready for adding a sales order
SDKCB5 | Call SORTOI Add Sales Order | Demonstrates calling the S/O Post business object using CALL-BO-POST allowing a new sales order to be added
SDKCB6 | Open an XML file and parse it | Demonstrates opening a physical XML file, loading this into the SYSPRO XML parser (COMPAR) and iterating through all the elements and nodes.

Overview of calling a business object from a Net Express program

The following is a brief explanation of how to call business objects from a Net Express application. The sample program SDKCB1 is used as an example.

The basic elements of this program are:

The program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMQR2-XMLOUT TO NULL. It is best practice to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

In the SDKCB1 example it requests a customer code by calling the dialog system. It then performs a READ-ROUTINE to fetch the customer name using the ARSQRY business object.

The READ-ROUTINE uses various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build an XML string that will be used as the input to the A/R Query business object (ARSQRY). The XML input is described in the e.net object model reference against the Query.Query method.

The program calls the A/R Query business object using the CALL-BO-QUERY function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. In this example program it displays a message box using INVOKE-MESSAGE-BOX with the exception text showing the exception number in the message box heading.

If the business object returned successfully (zero in LINK-COM-RETURN) then the program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be parsed looking for the value of a single XML element

2. The returned XML can be parsed looking for multiple XML elements allowing you to traverse the XML tree finding any XML element values

In this example the program will look for the single XML element <name> and return it's value to be shown in the dialog system.

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

The following copybooks are required to be included in your source code to build the XML string and to parse the XML returned from the business object. This code fragment is taken from SDKCB1.CBL. The lines marked 'xml' are the ones specifically related to XML building and parsing.

xml COPY "COMPAR.WRK". *> XML Parser fields

xml COPY "COMCRX.WRK". *> Create XML fields

*

COPY "DSCTL.WRK".

COPY "STANDARD.WRK".

COPY "WWLINK.WRK".

COPY "LNK.WRK".

*

01 LNK2.

xml COPY "COMQR2.LNK".

*

LINKAGE SECTION.

COPY "LINK.WRK". *> Standard linkage

01 LINK2 PIC X.

*

PROCEDURE DIVISION USING LINK, LINK2.

*

** You MUST set the object references to NULL before PROBEGIN.PRO

** The reason is that PROBEGIN.PRO may branch to ENDJOB where

** they may be tested for NULL in the ENDJOB function

xml PERFORM COMPAR-INITIALIZE-OBJECTS.

xml SET COMQR2-XMLOUT TO NULL.

*

COPY "PROBEGIN.PRO".

xml COPY "COMCRX.PRO". *> Build XML string

xml COPY "COMPAR.PRO". *> XML parser

For a more detailed example see the topic Calling Business Objects Sample program (SDKCB1).

See also

e.net Overview, Calling Business Objects Sample program (SDKCB1), Advantages of Calling Business Objects, Licensing Implications when calling Business Objects, CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST, Query.Query, Transaction.Build, Transaction.Post, Setup.Add, Setup.Update, Setup.Delete


Calling Business Objects Sample Program (SDKCB1)

SYSPRO SDK

Calling Business Objects

Calling Business Objects Sample Program Overview (SDKCB1)

The program SDKCB1.CBL is a basic sample program that demonstrates how to call a business object from a Net Express program. This program is designed to prompt the operator for a customer code and to call the AR Query business object to retrieve and show the customer name. To run it from the SYSPRO main menu use File > Run > SDKCB1 or add SDKCB1 to your Favorites menu.

There is a similar sample program (SDK001) that asks a stock code and shows it's description and mass - it demonstrates how to access the SYSPRO database directly. This overview of SDKCB1 will not cover the Dialog System. Please refer to the documentation against SDK001 for information about the Dialog System.

Once you have installed the SYSPRO Software Development Kit (see Setting up a Development Environment) you will find the relevant source code as follows:

\rnd60\source\SDKCB1.CBL | Program source code
\rnd60\gui\SDKCB1.GS | Screenset
\rnd60\gui\SDKCB1.CPB | Data block copybook

The remainder of this document describes the source code SDKCB1.CBL. Please refer to the documentation against SDK001 for information about the Dialog System.

Source code structure

This program is a typical SYSPRO program that has standard elements. These are explained below. Note that the source code defines the business logic, in addition the source code calls the dialog system to provide any user-interface. The user-interface may be running on the same or a different computer in the case of a client/server system. The data block is used to pass information to and from the screenset.

Comment header block

The first few lines of every SYSPRO program consists of a comment header block. This is a consistent method of documenting the program name, description and other settings. See the example below.

Syspro use some proprietary utilities that read these comment blocks to create various databases – including the IMPPRG.IMP file.

For more information see Source comment header block.

**************************************************************

** SYSPRO **

** Copyright (c) 1994-2009 SYSPRO Ltd. All rights reserved.**

**************************************************************

** Program name : SDKCB1 **

** Description : SYSPRO SDK Call ARSQRY Get Single Elemnt**

** Run from menu : Yes **

** Can be secured: Yes **

** Owner : Core **

**************************************************************

*

* Date Init PDR Description

003 * 16/02/05 RJH 68351 Use new XML build routines in COMCRX.PRO

* rather than obsolete ones in PROARRAY.PRO

002 * 03/08/04 RJH 64226 Improve sample program

* Redeveloped to use new CALL-BO-QUERY

* function passing and receiving XML

001 * 30/03/04 KKD 61500 Use new routine to call business object

000 * 05/12/02 KKD 53971 New program for SYSPRO60

*

*

** Notes on this sample program

** ----------------------------

** This program is designed to demonstrate how to call a business

** object from within a SYSPRO application. It is provided 'as is'

** and is not designed to perform any specific business function.

etc...

The remainder of the comments are not shown here. They provide an overview of the program and the main features demonstrated.

File definition and CLASS-CONTROL

After the comment header block comes the file definition section. This defines the data files used by the program. As this program does not access the SYSPRO database directly but calls the AR Query Business Object (ARSQRY) to retrieve information about the customer only the standard 'report' file (ADMREP) is included.

The XML strings passed to and retrieved from the AR Query business object are character arrays and ordered collections. These Net Express Objects require definition in the CLASS-CONTROL SECTION as shown in the example below.

FILE-CONTROL.

*

COPY "ADMREP.SEL". *> Printer SELECT copybook

*

***************************************************************

** The class control must define the OrderedCollection and **

** CharacterArray classes. **

***************************************************************

CLASS-CONTROL.

OrderedCollection is class "ordrdcll"

characterarray is class "chararry".

*

DATA DIVISION.

FILE SECTION.

*

FD ADMREP.

COPY "ADMREP.MAS". *> Report record layout

Note that from SYSPRO 6.1 it is recommended that you do not hard-code the CLASS-CONTROL clauses but rather use the copybook named CLASS.WRK. This is done using the following code fragment:

FILE-CONTROL.

*

COPY "ADMREP.SEL". *> Printer SELECT copybook

*

COPY "CLASS.WRK".

. *> Do not remove the dot from this line

*

DATA DIVISION.

FILE SECTION.

*

FD ADMREP.

COPY "ADMREP.MAS". *> Report record layout

Note that there is a line immediately following the 'CLASS.WRK' line that consists of only a dot. This is to terminate the CLASS-CONTROL section as the copybook CLASS.WRK does not end with a dot. The reason for this is to allow additional class control clauses to be added after the CLASS.WRK copybook.

Working storage section

After the file definition comes the working storage section. This is where you define all variables, constants and working fields to be used by your program. See the example below.

For consistency all standard SYSPRO programs have a WHAT-STRING defined as the first part of the working storage section. This is a string that defines the version. When compiled the special string @(#) even makes this string available in the compiled object code. The field VERS is a mandatory field defining the 3 digit program version.

Next comes the specific fields for each program. This is a free format area where you can define fields to be used, variables, constants, strings and any other type of data required by the program.

At the end of the working storage section are typically a number of standard copybooks. These copybooks define a whole host of common fields used by standard routines. In addition they define linkages required when calling other programs and when calling the screenset for your program. Note that SDKCB1.CPB is the name of the data block definition copybook.

WORKING-STORAGE SECTION.

*

01 WHAT-STRING VALUE "@(#) Program version .003".

03 FILLER PIC X(25).

03 VERS PIC 9(3).

01 WHAT-DUMMY PIC X(2) VALUE X"0D0A".

*

01 EDIT-EXCEPTION.

03 EDIT-EXCEPTION-NUM PIC 9(6).

*

COPY "SDKCB1.CPB".

*

** Standard SYSPRO copybooks

COPY "COMPAR.WRK". *> XML Parser fields

COPY "COMCRX.WRK". *> Create XML fields

*

COPY "DSCTL.WRK".

COPY "STANDARD.WRK".

COPY "WWLINK.WRK".

COPY "LNK.WRK".

*

01 LNK2.

COPY "COMQR2.LNK".

*

LINKAGE SECTION.

COPY "LINK.WRK". *> Standard linkage

01 LINK2 PIC X.

The linkage section

This section defines parameters that are passed to your program. Standard SYSPRO programs have a common linkage that is passed between all programs - this is defined in LINK.WRK. When using this standard linkage simply use the coding shown below. Note that there is a dummy linkage field called LINK2 that is generally unused. You should still include it as standard routines make reference to this field.

LINKAGE SECTION.

COPY "LINK.WRK". *> Standard linkage

01 LINK2 PIC X. *> Dummy 2nd linkage

Procedure division

The procedure division is where all the work actually happens. This is where the program starts. Whilst the scope of what can be done in the procedure division is large generally the program will perform the following basic steps.

  1. Run through PROBEGIN.PRO

  2. Run through any other .PRO copybooks

  3. Build and open any files required

  4. Initialize any fields required

  5. Call a screenset to allow the user to make selections or perform actions

  6. Handle the functions required by the user

  7. Shutdown gracefully, closing files, removing Windows left behind, returning to the calling program or menu

The sample program is designed to prompt the operator for a customer code, it then builds a simple XML string and passes this to the AR Query (ARSQRY) business object. This returns an XML string that this program must parse to retrieve the customer name which is then passed back to the dialog system so that it can be shown.

Initialization

Every SYSPRO program that uses the Dialog system must start with the PROBEGIN.PRO copybook. Programs that call Business objects should initialize the XML parser objects and initialize the XML object returned by the business object before PROBEGIN.PRO is executed. This is important as these objects must be finalized at the ENDJOB procedure and if they have not been initialized first this can cause problems.

After initializing the XML objects you should include the PROBEGIN.PRO copybook. This copybook defines many functions that are commonly used by SYSPRO programs. See Functions by name and Functions by type for a full list of the available functions.

Next the routines to build XML strings (COMCRX.PRO) and routines to parse XML strings returned from the business object (COMPAR.PRO) are included.

Then sample program initializes the screenset data block and control block. See below.

PROCEDURE DIVISION USING LINK, LINK2.

*

** You MUST set the object references to NULL before PROBEGIN.PRO

** The reason is that PROBEGIN.PRO may branch to ENDJOB where

** they may be tested for NULL in the ENDJOB function

PERFORM COMPAR-INITIALIZE-OBJECTS.

SET COMQR2-XMLOUT TO NULL.

*

COPY "PROBEGIN.PRO".

COPY "COMCRX.PRO". *> Build XML string

COPY "COMPAR.PRO". *> XML parser

*

** Initialize dialog system fields

INITIALIZE DS-CONTROL-BLOCK.

INITIALIZE D-DATA-BLOCK.

MOVE "SDKCB1" TO SCREENSET-NAME.

MOVE DSG-PUSH-SET TO DSG-CONTROL.

Event loop

Next the program will typically call the screenset and wait for the operator to respond. This is the task of the event loop. This consists of a simple loop, calling the screenset, detecting the actions required, performing the actions and returning for any other events. The event loop in the sample program is shown below.

************************************************

** Main Dialog system message handling loop **

************************************************

MAIN-DS-LOOP.

PERFORM CALL-DS.

*

IF D-S-FR-MSG = "read"

PERFORM READ-ROUTINE.

*

GO TO MAIN-DS-LOOP.

Main program functions

The functions to be performed by most programs are called from the event loop. In our example this is where we are going to builds a simple XML string and passes this to the AR Query (ARSQRY) business object. This returns an XML string that this program must parse to retrieve the customer name which is then passed back to the dialog system so that it can be shown.

Building an XML string

The sample program will first build an XML string that looks similar to the following.

<query>

<key>

<customer>CUS001</customer>

</key>

</query>

In this example the customer code is assumed to be 'CUS001'.

How do I know what XML to pass to the business object?

To see all the possible XML elements and how they should be constructed you should see the appropriate XML instances and XSD schemas defined in the XML Schema Reference. The Object Model Reference briefly describes each object and contains links to the XML/XSD schemas. See Query.Query, Transaction.Build, Transaction.Post, Setup.Add, Setup.Update, Setup.Delete for this information. For the most complete and up-to-date information about available business objects and their schemas please use the SYSPRO Support Zone Business Object Reference library.

The following code shows how the XML string is built. Note D-CUSTOMER is the field passed from the data block.

*

** Create the XmlIn string to call ARSQRY. For example:

** <query>

** <key>

** <customer>CUS001</customer>

** </key>

** </query>

*

** First create the root element - adds standard XML prolog

** This creates an object called 'ARRAY-OBJECT'

MOVE "query" TO XML-ROOT-NAME.

PERFORM CREATE-XML-HEADER.

*

** Create the rest of the XmlIn string

MOVE "<key>" TO ARRAY-DATA.

MOVE 5 TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

*

MOVE "customer" TO XML-TAG-NAME.

MOVE D-CUSTOMER TO XML-TAG-VALUE.

PERFORM OUTPUT-ELEMENT.

*

MOVE "</key>" TO ARRAY-DATA.

MOVE 6 TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

*

MOVE "</query>" TO ARRAY-DATA.

MOVE 8 TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

*

** Complete the XmlIn string

PERFORM ARRAY-FINAL-CREATE.

The function CREATE-XML-HEADER initializes the XML prolog and root elements (see Well Formed XML) for an object called ARRAY-OBJECT and must be performed before any other use of this object.

Next the sample program opens a <key> element using the ARRAY-CREATE function. This simply adds a new node to the ARRAY-OBJECT.

Then the programs adds <customer>CUS001</customer> using the OUTPUT-ELEMENT function. This requires the element name and element value. The OUTPUT-ELEMENT function handles character entities - see the topic Well Formed XML.

Then the program closes the open nodes by adding </key> and </query> using the ARRAY-CREATE function.

Lastly the program finalizes the ARRAY-OBJECT object using ARRAY-FINAL-CREATE - this closes the root element.

Calling the A/R Query Business Object

The sample program calls the AR Query (ARSQRY) business object using the CALL-BO-QUERY function. As we are calling a Query business object we must set the input parameter COMQR2-XMLIN to the value of the XML string that we have already built. See the following code.

*

** Build up the linkage and call the business object

MOVE SPACES TO LINK-EXTRA.

SET COMQR2-XMLIN TO ARRAY-OBJECT.

MOVE "ARSQRY" TO WW-PROG-NAME.

PERFORM CALL-BO-QUERY.

Test for any Exceptions

After calling a business object you must test to see if an exception was returned. Exceptions are fatal problems that the business object encountered causing it to exit prematurely.

The field LINK-COM-RETURN has a non-zero value to indicate that an exception has occurred. In this case the field LINK-EXTRA contains a description of the exception. You will often use the INVOKE-MESSAGE-BOX function to display the exception message.

This is demonstrated in the following code.

*

** Check for any exceptions - error message is in LINK-EXTRA

** We will use a simple Message box for the exception message

IF LINK-COM-RETURN <> ZEROS

MOVE LINK-COM-RETURN TO EDIT-EXCEPTION-NUM

MOVE SPACES TO LINK-MSG-HDG

STRING "Exception Raised (" DELIMITED BY SIZE

EDIT-EXCEPTION DELIMITED BY SIZE

")" DELIMITED BY SIZE

INTO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Exception}" TO D-NAME

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO READ-END.

Parse the XML returned from the Business Object

If no exceptions occurred then we will typically parse the XML returned from the business object. As we used the CALL-BO-QUERY function the XML output is returned in COMQR2-XMLOUT.

The SYSPRO XML parser (COMPAR) is relatively simple to use. First you should set the object COMPAR-OBJECT to the XML output COMQR2-XMLOUT.

Then you should use the COMPAR-PARSE-XML function to start the XML parsing process. This performs various tests on the XML and returns the number of elements in the field COMPAR-NODE-COUNT. If the XML is not well formed or it fails other basic tests then it can return an exception that can be handled similarly to that mentioned above.

After using COMPAR-PARSE-XML we are going to use the simple COMPAR-SELECT-SINGLE-NODE function to look for the single XML element <name> and return the value in COMPAR-SINGLE-VALUE. This function is described in more detail in the topic Parsing XML - Return a Single Element.

Lastly this is moved to the data block field D-NAME where the screenset will refresh and show the customer name.

The following code shows this.

*

** Parse the XML - if invalid then goes to ENDJOB with exception

** If valid this returns the number of nodes

SET COMPAR-OBJECT TO COMQR2-XMLOUT.

MOVE "N" TO COMPAR-TO-ENDJOB.

PERFORM COMPAR-PARSE-XML.

MOVE "Y" TO COMPAR-TO-ENDJOB.

IF LINK-COM-RETURN <> ZERO

MOVE "XML Parsing Message" TO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Xml Parse Error}" TO D-NAME

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO READ-END.

*

** Select the single element '<name>' and retrieve value

MOVE "name" TO COMPAR-QUERY.

PERFORM COMPAR-SELECT-SINGLE-NODE.

*

** Return the name to the screenset so it can be shown

MOVE COMPAR-SINGLE-VALUE TO D-NAME.

Shutdown

The final process is to close the program gracefully. This is defined by the ENDJOB routine. Generally the ENDJOB routine will close any open files, exit the dialog system and use the EXIT PROGRAM statement to return control to the calling program or menu.

In addition, as we are calling a business object, it is very important that we finalize any objects and resources used by the XML parser and cancel the XML parser from memory.

Note that the screenset can branch to this ENDJOB routine by using a S-EXIT function without the application having to have specific coding to handle this. Because of this the ENDJOB function is mandatory for all SYSPRO programs.

**********************************************

** End of program **

** Must finalize any objects still in use **

**********************************************

ENDJOB.

PERFORM COMPAR-FINALIZE-OBJECTS.

PERFORM COMPAR-CANCEL. *> Cancel COMPAR from memory

PERFORM CLOSE-ALL-FILES.

PERFORM QUIT-DS.

EXIT PROGRAM.

Further reading

The above has demonstrated a typical, but simple, example of how a SYSPRO program can be used to call a business object. It is suggested that you familiarize yourself with this functionality, including using Net Express Animator to step through the source code. See Setting up a SYSPRO Development Environment if you have not already done so. You can then do the same with the other Source code samples supplied as part of the SYSPRO SDK.

Specifically see the sample programs SDKCB2 through SDKCB6 that demonstrate use of the other types of business objects.

A thorough understanding of the standard functions available in PROBEGIN.PRO and the standard functions available from the Dialog system will allow you to develop sophisticated custom applications.

See also

Parsing XML - Return a Single Element, Source code samples, Functions by name, Functions by type, Setting up a SYSPRO Development Environment, Basic Sample Program (SDK001), ENDJOB, PROBEGIN.PRO


Advantages of Calling Business Objects

SYSPRO SDK

Calling Business Objects

Advantages of using Business Objects

There are several advantages to calling business objects from your Net Express programs rather than directly accessing the SYSPRO database or calling 'traditional' SYSPRO programs.

The advantages include:

The interface to the business objects is completely described in the XML schemas

This SDK documentation describes the XSD schemas and XML instances for all current business objects. See the documentation covering the methods Query.Query, Transaction.Build, Transaction.Post, Setup.Add, Setup.Update, Setup.Delete.

In addition the Support Zone at www.syspro.com contains a business object reference library with the most up-to-date information.

The XML interfaces will not be broken with subsequent releases of SYSPRO

Additional XML elements may be utilised in future but correct use of the XML parsing logic will ensure that existing applications will work unchanged when new XML elements are accepted or returned from the business objects.

You do not need to worry about changes to the underlying SYSPRO database

The business objects will return the XML regardless of the underlying database structure or whether the company is using a SQL Server or C-ISAM based database.

The business objects will seamlessly handle any future changes to field sizes

You may still need to handle future field size changes in your application but the interface to the business objects will not change.

All SYSPRO business rules are handled by the business object

If you access the SYSPRO database directly you would have to apply these business rules in your application. This has the advantage of future enhancements to the business rules in SYSPRO will be seamlessly handled by your application.

Platform independence

The business objects and XML functions are all designed to work regardless of whether you are using SYSPRO on a Windows or Unix server based configuration.

See also

Calling Business Objects Overview, Calling Business Objects Sample program (SDKCB1), CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST


Licensing Implications when Calling Business Objects

When you call a business object from your Net Express program in a SYSPRO environment there are no e.net licensing considerations. The only requirement is that each business object requires that the appropriate SYSPRO module is licensed.

For example the A/R Query business object (ARSQRY) requires that the Accounts Receivable module is licensed for the current company. There are no e.net licensing requirements.

e.net Solutions developers accessing business objects using a COM environment are required to have licensed the Functional Area to which the business object belongs. See the topic e.net Licensing Overview. This is not relevant for Net Express developers accessing the business objects in a non-COM environment.

See also

Calling Business Objects Overview, Calling Business Objects Sample program (SDKCB1), Advantages of Calling Business Objects, CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST


Parsing XML - Return a Single Element

SYSPRO 6.0 issue 009 onwards contains an XML parser that can be used to process XML returned from a business object.

See the topic Calling Business Objects Sample Program (SDKCB1) for a walk through of the entire source code in a simple application that calls a business objects and parses the returned XML.

The XML parser supplied with SYSPRO provides two styles of parsing:

1. Look for and retrieve a single XML element in the XML string

2. Step through the XML returning each and every element

This topic covers the first of these methods - returning a single XML element. The second method is described in the topic Parsing XML - Return Multiple Elements.

Pre-requisites

The remainder of this topic uses the sample program SDKCB1 provided as part of the SYSPRO SDK. It assumes that you have already called the appropriate business object and have ensured that no exceptions have occurred.

In the SDKCB1 example we called a Query business object. This returns the XML object in the field COMQR2-XMLOUT.

Using the XML parser

The SYSPRO XML parser (COMPAR) is relatively simple to use.

First you should set the object COMPAR-OBJECT to the XML output object COMQR2-XMLOUT.

Then you should use the COMPAR-PARSE-XML function to start the XML parsing process. This performs various tests on the XML and returns the number of elements in the field COMPAR-NODE-COUNT. If the XML is not well formed or it fails other basic tests then it can return an exception. The exception message is stored in the field LINK-EXTRA.

After using COMPAR-PARSE-XML we are going to use the simple COMPAR-SELECT-SINGLE-NODE function to look for the single XML element <name> and return the value in COMPAR-SINGLE-VALUE.

The lines marked 'xml' in the following code fragment from SDKCB1 demonstrate this.

*

** Parse the XML - if invalid then goes to ENDJOB with exception

** If valid this returns the number of nodes

xml SET COMPAR-OBJECT TO COMQR2-XMLOUT.

MOVE "N" TO COMPAR-TO-ENDJOB.

xml PERFORM COMPAR-PARSE-XML.

MOVE "Y" TO COMPAR-TO-ENDJOB.

IF LINK-COM-RETURN <> ZERO

MOVE "XML Parsing Message" TO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Xml Parse Error}" TO D-NAME

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO READ-END.

*

** Select the single element '<name>' and retrieve value

xml MOVE "name" TO COMPAR-QUERY.

xml PERFORM COMPAR-SELECT-SINGLE-NODE.

*

** Return the name to the screenset so it can be shown

MOVE COMPAR-SINGLE-VALUE TO D-NAME.

If you want to return the elements <name> and <telephone> you can call COMPAR-SELECT-SINGLE-NODE twice. For example:

*

** Select the single element '<name>' and retrieve value

MOVE "name" TO COMPAR-QUERY.

PERFORM COMPAR-SELECT-SINGLE-NODE.

MOVE COMPAR-SINGLE-VALUE TO D-NAME.

*

** Select the single element '<telephone>' and retrieve value

MOVE "telephone" TO COMPAR-QUERY.

PERFORM COMPAR-SELECT-SINGLE-NODE.

MOVE COMPAR-SINGLE-VALUE TO D-TELEPHONE.

In the case where an XML element is repeated many times you should see the topic Parsing XML - Return Multiple Elements.

Shutdown

Once the XML parser has been invoked using the COMPAR-PARSE-XML function you should finalize any objects and resources used by the XML parser and cancel the XML parser from memory. This is shown in the following code fragment often performed in the ENDJOB paragraph.

PERFORM COMPAR-FINALIZE-OBJECTS. *> Finalize XML objects

PERFORM COMPAR-CANCEL. *> Cancel COMPAR from memory

See also

Calling Business Objects Sample Program (SDKCB1), Parsing XML - Return Multiple Elements, ENDJOB


Parsing XML - Return Multiple Elements

SYSPRO 6.0 issue 009 onwards contains an XML parser that can be used to process XML returned from a business object.

See the topic Calling Business Objects Sample Program (SDKCB1) for a walk through of the entire source code in a simple application that calls a business objects and parses the returned XML.

The XML parser supplied with SYSPRO provides two styles of parsing:

1. Look for and retrieve a single XML element in the XML string

2. Step through the XML returning each and every element

This topic covers the second of these methods - returning multiple elements. The first method is described in the topic Parsing XML - Return a Single Element.

Pre-requisites

The remainder of this topic uses the sample program SDKCB2 provided as part of the SYSPRO SDK. It assumes that you have already called the appropriate business object and have ensured that no exceptions have occurred.

In the SDKCB2 example we called a Query business object. This returns the XML object in the field COMQR2-XMLOUT.

Using the XML parser

The SYSPRO XML parser (COMPAR) is relatively simple to use.

First you should set the object COMPAR-OBJECT to the XML output object COMQR2-XMLOUT.

Then you should use the COMPAR-PARSE-XML function to start the XML parsing process. This performs various tests on the XML and returns the number of elements in the field COMPAR-NODE-COUNT. If the XML is not well formed or it fails other basic tests then it can return an exception. The exception message is stored in the field LINK-EXTRA.

After using COMPAR-PARSE-XML we are going to use the COMPAR-GET-NEXT function to iterate through the returned XML.

Each time the COMPAR-GET-NEXT function is performed two flags will be set. COMPAR-NEW-NODE will be set to 'Y' when a new node has been opened and COMPAR-END-NODE will be set to 'Y' when a node has been closed.

In addition the fields COMPAR-TAG-1, COMPAR-TAG-2, COMPAR-TAG-3, etc are updated with the element names (and whenever this is not a new/end node the element values).

Note that the parser COMPAR is limited to a maximum of 10 nested levels of XML elements - these are output to the fields COMPAR-TAG-1 through COMPAR-TAG-10.

The following example shows how these fields are returned after each COMPAR-GET-NEXT function assuming the following XML is being parsed.

<ARStatement>

<header>

<Customer>CUS001</Customer>

<Name>Customer 1</Name>

<Telephone>555-1234</Telephone>

<CurrentBalance>10721.98</CurrentBalance>

</header>

</ARStatement>

compar-new-node | compar-end-node | compar-tag-1 | compar-tag-2 | compar-tag-3 | compar-tag-4
Y |  | arstatement |  |  |
Y |  | arstatement | Header |  |
 |  | arstatement | Header | Customer | CUS001
 |  | arstatement | Header | Name | Customer 1
 |  | arstatement | Header | Telephone | 555-1224
 |  | arstatement | Header | CurrentBalance | 10721.98
 | Y | arstatement | Header |  |
 | Y | arstatement |  |  |

The following code fragment from SDKCB2 demonstrate the logic to look for the elements <Name>, <Telephone> and <CurrentBalance> returned from the A/R Query (ARSQRY) business object.

*

*

***************************************************************

** Routine to parse the returned XML. Iterates through the **

** XML looking for the required element names **

***************************************************************

LOOKUP-XML.

PERFORM LOOKUP-XML-1 THRU LOOKUP-XML-END.

LOOKUP-XML-1.

IF COMPAR-WS-READ >= COMPAR-NODE-COUNT

GO TO LOOKUP-XML-END.

*

** Retrieve next XML element name and value

** See COMPAR-TAG-x for names and values

PERFORM COMPAR-GET-NEXT.

*

** Continue looping if find an open node (no value)

IF COMPAR-NEW-NODE = "Y" OR COMPAR-END-NODE = "Y"

GO TO LOOKUP-XML-1.

*

** Look for the element names we want

IF COMPAR-TAG-3 = "Name"

MOVE COMPAR-TAG-4 TO D-NAME.

IF COMPAR-TAG-3 = "Telephone"

MOVE COMPAR-TAG-4 TO D-TELEPHONE.

IF COMPAR-TAG-3 = "CurrentBalance"

MOVE COMPAR-TAG-4 TO NUMB-R

PERFORM NUMB-CHECK

MOVE NUM-VAL TO D-BALANCE.

GO TO LOOKUP-XML-1.

LOOKUP-XML-END.

If you want to return just a single element then consider using the COMPAR-SELECT-SINGLE-NODE function described in the topic Parsing XML - Return a Single Element.

Shutdown

Once the XML parser has been invoked using the COMPAR-PARSE-XML function you should finalize any objects and resources used by the XML parser and cancel the XML parser from memory. This is shown in the following code fragment often performed in the ENDJOB paragraph.

PERFORM COMPAR-FINALIZE-OBJECTS. *> Finalize XML objects

PERFORM COMPAR-CANCEL. *> Cancel COMPAR from memory

See also

Calling Business Objects Sample Program (SDKCB1), Parsing XML - Return a Single Element, ENDJOB


File status codes

Summary of Common Net Express File Status Codes

Status | Also known | Description | ANSI 85
00 | 0-048 | Successful |
02 | 0-050 | Successful with the following information a. where duplicate key allowed a READ has been issued where 2 or more keys exist b. a WRITE or REWRITE generated a duplicate alternate key where the key has been defined WITH DUPLICATES |
04 | 0-052 | Successful with the following information The length of the record does not conform to the fixed file attributes | ANSI 85
05 | 0-053 | Successful with the following information File did not exist prior to an OPEN I-O | ANSI 85
10 | 1-048 | End of file |
22 | 2-050 | a. Duplicate key in primary WRITE/REWRITE b. Duplicate key in alternate key where alternates are not allowed. |
23 | 2-051 | Record not found after READ Can indicate REWRITE when primary key changed |
24 | 2-052 | Boundary violation caused by index WRITE Usually means file size has reached max limit (1GB on Windows, 2GB of Unix) | ANSI 85
30 | 3-048 | Boundary violation |
34 | 3-052 | Boundary violation |
35 | 3-053 | Open Input – file does not exist | ANSI 85
37 | 3-055 | An OPEN statement has been attempted on a file which does not support this open mode (e.g. OPEN I-O on a sequential file) | ANSI 85
39 | 3-057 | A conflict has been found between the fixed file attributes and that specified for the program. For e.net business objects ensure the file name is defined in WORKING STORAGE or FILE.WRK. | ANSI 85
41 | 4-049 | An OPEN has been attempted on a file already opened | ANSI 85
42 | 4-050 | A CLOSE has been attempted on a file already closed | ANSI 85
44 | 4-052 | A REWRITE has been attempted on a line sequential file and the record length has changed | ANSI 85
46 | 4-054 | A READ NEXT has been attempted when no current record exists. | ANSI 85
47 | 4-055 | A READ or START has been attempted on a file not opened INPUT or I-O | ANSI 85
48 | 4-056 | A WRITE statement has been attempted on a file not opened in the OUTPUT, I-O or EXTEND modes | ANSI 85
49 | 4-057 | A DELETE or REWRITE statement has been attempted on a file that is not opened I-O | ANSI 85

Status | Description |
9-002 | File not open when access attempted |
9-004 | Illegal file name – often blank |
9-005 | Illegal device specification |
9-006 | Attempt to write to a file opened for input |
9-007 | Disk space exhausted |
9-008 | Attempt to read a file opened for output |
9-009 | No room in directory or directory does not exist Can also mean that the file you are attempting to open contains special characters such as '<', '>', '*', '?' etc. |
9-010 | File name not supplied |
9-012 | Attempt to open a file that is already open |
9-013 | File not found |
9-014 | Too many files opened simultaneously |
9-015 | Too many indexed file open |
9-016 | Too many devices open |
9-017 | Record error (probably zero length) |
9-018 | Invalid end of file |
9-019 | Rewrite error – open mode conflict |
9-020 | Device or resource busy |
9-021 | Attempted open on a directory |
9-022 | Illegal or impossible access mode for OPEN |
9-023 | Illegal or impossible access mode for CLOSE |
9-024 | Disk I/O error |
9-025 | Operating system data error |
9-026 | Block I/O error |
9-027 | Device not available |
9-028 | No space on device |
9-029 | Attempt to delete an open file |
9-030 | File system is read only |
9-031 | Not owner of file |
9-032 | Too many indexed files |
9-033 | Physical I/O error |
9-034 | Incorrect mode or file descriptor |
9-035 | Attempt to access a file with incorrect permission |
9-036 | File already exists |
9-037 | File access denied |
9-038 | Disk not compatible |
9-039 | File not compatible |
9-040 | Language initialization not setup correctly |
9-041 | Corrupt index file |
9-042 | Attempt to write on broken pipe |
9-043 | Data or Index portion missing for indexed file |
9-065 | File locked | 9A
9-066 | Attempt to write a duplicate record to an indexed file | 9B
9-067 | Indexed file not open | 9C
9-068 | Record locked | 9D
9-069 | Illegal argument to ISAM module | 9E
9-070 | Too many indexed file open | 9F
9-071 | Bad indexed file format | 9G
9-072 | End of indexed file | 9H
9-073 | No record found in indexed file | 9I
9-074 | No current record in indexed file | 9J
9-075 | Indexed data file name too long | 9K
9-077 | Internal ISAM module failure | 9M
9-078 | Illegal key description in indexed file | 9N
9-081 | Key already exists in indexed file | 9Q
9-100 | Invalid file operation |
9-101 | Illegal operation on indexed file |
9-102 | Sequential file with non integral number of records |
9-104 | Null file name |
9-105 | Memory allocation error |
9-135 | File must not exist |
9-139 | Record length or key length inconsistency |
9-141 | File already opened – cannot be opened |
9-142 | File not open – cannot be closed |
9-146 | No current record defined for READ NEXT |
9-147 | Wrong open mode or access mode for READ/START |
9-148 | Wrong open mode or access mode for WRITE |
9-149 | Wrong open mode or access mode for REWRITE/DELETE |
9-150 | Program abandoned at user request |
9-152 | REWRITE on file not opened I-O |
9-158 | Attempt to REWRITE to a line-sequential file |
9-159 | Malformed line sequential file |
9-161 | Missing header - If running in a COM environment this often means that the file name has not been defined in WORKING-STORAGE. |
9-180 | Invalid end of file |
9-183 | Attempt to open line sequential file I-O |
9-188 | File name too large |
9-194 | File size too large |
9-213 | Too many record locks |
9-219 | Operating system shared file limit exceeded |

See the topic Testing File Status Codes for practical advice on how to test for file codes.


Testing File Status Codes

History

Standard SYSPRO programs use the common field named STAT-CODE when defining the FILE STATUS clause in the SELECT statement.

For example the Inventory Buyer file (INVBUY) SELECT statement is:

SELECT INVBUY

ASSIGN INVBUY-DATA

ORGANIZATION INDEXED

ACCESS DYNAMIC

LOCK MANUAL WITH LOCK ON MULTIPLE RECORDS

FILE STATUS IS STAT-CODE

RECORD KEY IS INVBUY-KEY.

The field STAT-CODE is defined in the copybook STANDARD.WRK (that is included in all SYSPRO programs).

After each file access the Net Express file handler logic updates STAT-CODE so that your program can test the success or otherwise of the file action.

The following summarises the typical tests that you should perform after each file access. The Inventory Buyer table (INVBUY) is used in the examples below.

OPEN

Standard SYSPRO files are typically opened using the XXXXXX-BUILD-AND-OPEN-IO-COMER function. This builds the file name, opens the file I-O and performs the COMER function. The COMER function tests the status code STAT-CODE and if any error occurs it will display a message and then issue a GO TO ENDJOB.

Therefore you do not typically need to add any additional logic to test the file status code after an OPEN.

Example code:

PERFORM INVBUY-BUILD-AND-OPEN-IO-COMER.

READ

Standard SYSPRO direct reads on the primary key typically use XXXXXX-READ. This reads a record using the primary key and returns the record area and STAT-CODE. You typically only check for a STAT-OK condition and manage it appropriately.

Example code:

PERFORM INVBUY-READ.

IF STAT-OK

PERFORM PROCESS-BUYER

ELSE

PERFORM BUYER-NOT-FOUND

END-IF.

In the event that you have previously read a record and subsequently attempt to read the same record then it is permissible to use the COMER function as in this instance your program logic is assuming that the record should still exist.

Example code:

PERFORM INVBUY-READ.

PERFORM COMER.

READ-LOCK

Standard SYSPRO direct reads where you require to attract a record lock use the READ-LOCK function. If the record is locked by someone else then you should test the STAT-LCK condition. If you detect a STAT-LCK condition your code could display an appropriate message and allow the operator to retry or exit. Alternatively you may wish to retry until the lock is released by the other user - in this situation consider using the READ-WAIT function that handles this without any additional code.

Example code:

PERFORM INVBUY-READ-LOCK.

IF STAT-LCK

PERFORM DISPLAY-RECORD-LOCKED-MSG

ELSE

IF STAT-OK

PERFORM PROCESS-BUYER

ELSE

PERFORM BUYER-NOT-FOUND

END-IF

END-IF.

READ-WAIT

Standard SYSPRO direct reads where you require to attract a record lock and will wait for others to release any existing locks use the READ-WAIT function. This is identical to using a READ-LOCK and looping continually when you receive a STAT-LCK condition.

Example code:

PERFORM INVBUY-READ-WAIT.

IF STAT-OK

PERFORM PROCESS-BUYER

ELSE

PERFORM BUYER-NOT-FOUND

END-IF.

Note that the READ-WAIT will never return a STAT-LCK condition.

START

Standard SYSPRO start logic to position the current record pointer - usually immediately followed by a READ-NEXT or READ-PREVIOUS - requires testing for the STAT-INVALID-KEY condition.

Example code:

PERFORM INVBUY-START-GE.

IF STAT-INVALID-KEY

GO TO NO-RECORDS.

Important note - on a SQL Server environment the START functions always return STAT-OK and therefore you will never receive a STAT-INVALID-KEY file status. The READ-NEXT following the START is used to validate the START/READ-NEXT logic - see the COMER mentioned below.

READ-NEXT

Standard SYSPRO logic to read the next record from the current record pointer forwards (usually preceded by a START) requires you to test for the STAT-AT-END condition. In addition you should use the COMER function - especially when running on a SQL Server environment.

Example code:

PERFORM INVBUY-READ-NEXT.

IF STAT-AT-END

GO TO END-OF-FILE.

PERFORM COMER.

Important - Failure to add the PERFORM COMER as shown above can result in SQL code appearing to hang. This is easiest to understand with the following example - suppose a column has been removed from the table by the end-user (a serious database issue!). Remember that the START logic always returns STAT-OK and therefore the first physical access on the SQL table will be the initial READ-NEXT. However the database will not return a STAT-AT-END condition. Therefore if you do not test the file status using PERFORM COMER then you will not detect an error. The program typically loops until a STAT-AT-END condition which (in this case) will never occur. The COMER function will display an appropriate message - in our example indicating that there is a missing column.

WRITE

Standard SYSPRO logic to insert records into the file using the WRITE function typically use the COMER function as a duplicate record is usually treated as 'fatal' and the program requires to branch to ENDJOB.

Example code:

PERFORM INVBUY-WRITE.

PERFORM COMER.

In addition you may test the STAT-DUP condition indicating that there was a duplicate record. This is not recommended.

REWRITE

Standard SYSPRO logic to update a record using the REWRITE function typically uses the COMER function as a missing record is usually treated as 'fatal' and the program requires to branch to ENDJOB.

Example code:

PERFORM INVBUY-REWRITE.

PERFORM COMER.

Important note - you should always precede a REWRITE by a read with lock so that you are locking the record and no one can update it. In addition you must perform the READ-LOCK or READ-WAIT and REWRITE inside a transaction. Typically:

Example code:

PERFORM BEGIN-TRANSACTION.

* Code to build primary key - then read and wait for lock

PERFORM INVBUY-READ-WAIT.

PERFORM COMER.

* Code to change record

PERFORM INVBUY-REWRITE.

PERFORM COMER.

PERFORM COMMIT-TRANSACTION.

CLOSE

Standard SYSPRO logic to close files is handled by the CLOSE-ALL-FILES function and is inserted into the ENDJOB paragraph.

Example code:

ENDJOB.

PERFORM CLOSE-ALL-FILES.

See also

ENDJOB, File Status Codes


Spacey File Names

History

Historically file names could not contain spaces. For example when typing file names from a command line a space character was used as a delimited between parameters as in the following example.

COPY FILE1.TXT FILE2.TXT

However later versions of Windows allow directories/folders to have spaces and/or the actual file names to have spaces as in the following example.

C:\Program Files\Syspro 6.0\This contains spaces.doc

When the folder and/or file name contains spaces this is called a spacey file name.

SYSPRO does not use spacey file names for either program names, screenset names or data file names. However when accessing data from third party systems – for example when importing data then spacey file names are supported. In addition SYSPRO itself may be installed in a spacey folder name such as:

C:\Program Files\Syspro

Using spacey file names from SYSPRO programs

All the Net Express routines to access files, check if a file exists, copy or delete a file and so on, use a space character as a delimiter. In this case whenever a spacey file name is used it must be surrounded by quotes.

There is a standard routine called QUOTE-VALID-FILE-NAME that can be used to test if a file name is spacey and to add the necessary quotes.

Note that non-Net Express systems must not have the quotes. This includes Win32 API calls and when storing file names in an XML or HTML document. In this case you should use the STRIP-VALID-FILE-NAME function to remove any quotes.

It is strongly recommended that you use these routines rather than attempt to perform this logic yourself.

See also

QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME


Temporary files

Introduction

This topic details how SYSPRO locates and uses temporary files and how a developer should generate temporary file names.

Why does SYSPRO require temporary files?

SYSPRO programs occasionally require temporary files. The reasons for these include:

  • Creating spooled report files to be previewed and/or printed

  • Passing temporary configurations between applications

  • Creating temporary sort files

  • Creating temporary files on a server that are to be moved to the client PC in a client/server environment

What naming conventions are used?

Generally temporary files are created in a temporary directory with a file name of _Tuuuu999.DAT (under Unix the .DAT is not appended).

Where uuuu is the 4 digit user number that is unique to all operators currently logged into this instance of SYSPRO and 999 is a 3 digit number that is incremented by one for each temporary file required by the user. In some cases different extensions are used. For example _T0001001.XML

See below for how SYSPRO identifies the temporary directory.

I can see some _T*.DAT files on my system. Can I delete them?

Generally SYSPRO programs remove the temporary files after they have been used. Therefore if no one else is using SYSPRO then you can delete the _T*.* files. These may have been inadvertently left after a program/system failure.

Please ensure that no one else is using SYSPRO as they may be in the process of using these files. It's safe to remove these files in the server boot up process.

How does SYSPRO identify the temporary directory to be used?

SYSPRO has two methods of identifying the temporary directory to be used.

  1. The TEMP environment variable

  2. The IMPTMP= entry in an IMPACT.INI file

These are handled slightly differently depending on whether you are using a standalone, mapped drive or client/server environment.

Standalone and Mapped drive environment

In a mapped drive environment (network or standalone) SYSPRO will determine the temporary directory as follows:

  1. If there is a TEMP environment variable set on your PC then this will be used

  2. If there is not a TEMP variable then the IMPTMP= entry in the IMPACT.INI in SYSPRO's working directory will be used

Client/Server – Temporary files on the Server

In a client/server environment any temporary files on the server will be determined as follows:

  1. If there is a TEMP environment variable set on your server then this will be used

  2. If there is not a TEMP variable then the IMPTMP= entry in the IMPACT.INI on the server will be used.

Client/Server – Temporary files on the Client

In a client/server environment any temporary files on the client will be determined as follows:

  1. The IMPTMP= entry in the IMPACT.INI in SYSPRO's working directory on the client will be used

  2. If there is not an IMPTMP= entry then the TEMP environment variable set on your PC will be used

As a programmer how should I generate a temporary file name?

There is a routine called BUILD-TMPFIL that generates a unique file name. This routine ensures that the file name built is unique across all users currently logged into the SYSPRO system.

The result of this function is a file name in the field WW-FILE-NAME. You also must define a field called TMPFIL.

If you need a user-defined extension then you should use BUILD-TMPFIL-USER-EXT.

See also

BUILD-TMPFIL, BUILD-TMPFIL-USER-EXT, IMPACT.INI, SQL Server Creating Temporary Tables


Deleting files

Warning: Please take great care when deleting any files as there is no confirmation when using the functions discussed in this topic.

Deleting sequential and other single files

Use the DELETE-WW-FILE-NAME function to delete any file on the server.

The name must be quoted if it is a spacey file name. Use QUOTE-VALID-FILE-NAME to quote a spacey file name.

If the file is a sequential, or line sequential, data file then it must be closed before it can be deleted.

Sample code

* Code to delete a text file

MOVE "C:\Syspro\Temp\Report.txt" TO WW-FILE-NAME.

PERFORM DELETE-WW-FILE-NAME.

Deleting indexed files

If you are deleting an indexed file then you need to use the DELETE-INDEX-FILE function that deletes both the data and index portions.

This function requires the DEL.WRK and PRODEL.PRO copybooks to be included.

Note that the full path to the data portion of the ISAM file must be passed. The routine will delete this file and then remove the appropriate index portion. It is recommended that you use this routine to delete indexed files as it takes care of differences between operating systems.

The ISAM file must be closed before it can be deleted.

Sample code

* Code to delete the Inventory master file (data and index portion)

PERFORM INVMST-BUILD-DATA.

MOVE INVMST-DATA TO DELETE-FILE-NAME.

PERFORM DELETE-INDEX-FILE.

See also

spacey file name, QUOTE-VALID-FILE-NAME, DELETE-WW-FILE-NAME, PRODEL.PRO


Searching for Files

Introduction

Occasionally you may wish to scan a directory for files or sub-directories that match a specified pattern. For example you may want to find all the files named *.idx in the data directory.

SYSPRO contains several functions to make this as easy as possible.

Note that this function works on the Server in a client/server environment.

Overview of scanning a directory

There are several parts to scanning a directory looking for files that match a pattern.

Initialization

There is an X91-SCAN-INITIALIZE function that initializes the working fields in STANDARD.WRK. This should be performed before any of the other functions or fields are referenced.

You then specify the path and file name to be matched. This can contain the normal * and ? wildcards and can also contain a path. Note that spacey file names must be quoted. Examples include:

IMP*.EXE

REP*.?nt

c:\temp\*.txt

"c:\Program Files\SYSPRO\Data\*.idx"

On Unix platforms you specify an exact case and the paths should contain forward slashes (eg /data/*.idx)

On a Windows environment you must then specify the file attributes (in the field X91-ATTRIN) that are to be matched. The attributes supported each have a 78 level as shown below:

78 X91-ATT-READ-ONLY VALUE 1.

78 X91-ATT-HIDDEN VALUE 2.

78 X91-ATT-SYSTEM VALUE 4.

78 X91-ATT-VOLUME-LABEL VALUE 8.

78 X91-ATT-SUB-DIRECTORY VALUE 16.

78 X91-ATT-ARCHIVED VALUE 32.

These attributes can be summed to specify which files (in addition to normal files) are to be included.

For example if you are looking for Normal, Read-only and Archived files then you should sum the X91-ATT-READ-ONLY and X91-ATT-ARCHIVED values - this can be done as follows:

COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY + X91-ATT-ARCHIVED.

There are a number of selection criteria flags that can be set to make the scanning as simple as possible. These are:

X91-IGNORE-HID-SYS defaults to 1 - ignore hidden+system files

X91-IGNORE-DIRS defaults to 1 - ignore sub-directories in result set

X91-IGNORE-FILES defaults to 0 - include regular files

X91-IGNORE-DOT-DOT defaults to 1 - ignore the special directories '.' and '..'

Setting each of these to a value of 1 can be used to ignore hidden+system files, ignore sub-directories, ignore regular files and ignore the special directories '.' and '..' respectively - a value of zero indicates that the condition is not required. The default values are shown above.

In addition you can set a flag indicating that you want the 'date and time that the file was last updated' to be presented in an easy-to-use format. You do this by setting the flag X91-GET-DATETIME to a value of 1.

Note for Unix systems

Note that on a Unix system the concept of most of these attributes is not supported. The only attribute that is supported is the files/folders flag. If you want folders to be returned then you must use the following code:

MOVE 1 TO X91-IGNORE-FILES.

MOVE 0 TO X91-IGNORE-DIRS.

If you want only normal files (no folders) then the default values should be retained. Note that on Unix you cannot return both files and folders in a single list.

Looping through the resulting list

You then continually perform the X91-SCAN-DIRECTORY function fetching the first and subsequent files that match the pattern and attributes provided in the initialization phase.

Only files that match the attributes passed will be returned. In addition the logical flags (X91-IGNORE...) will also be applied. For example if you have indicated that sub-directories are not required then the result list will exclude any sub-directories, even if they match the other naming or attribute criteria.

Note that the returned files/sub-directories do not contain the path - only the filename portion is returned.

A status is returned indicating whether the end of list is reached.

If you wish to stop the function before the list has been exhausted you should use the X91-SCAN-TERMINATE-EARLY function to ensure that any resources are returned correctly. (this function should not be performed when a normal end-of-list status is returned)

Completing the function

When you have finished processing the matched files you should perform the X91-SCAN-COMPLETE function.

Note

You can use the SET-DIRECTORY-ON-SERVER and GET-DIRECTORY-ON-SERVER to save the current base directory, change to a different directory and use the scan function. You MUST restore the directory back to the base directory before you use any other function, such as calling a screenset, as SYSPRO requires the current directory to be the base directory at all times.

Input parameters

X91-FILEIN

Filename (including path and wildcards) to be matched on the server in a client/server environment.

This is case sensitive on Unix servers.

Note that spacey file names must be quoted.

X91-ATTRIN

This field contains a combination of the attributes that are to be included in the match. By default all normal files will be included. In addition you can sum one or more of the following 78 levels

78 X91-ATT-READ-ONLY VALUE 1.

78 X91-ATT-HIDDEN VALUE 2.

78 X91-ATT-SYSTEM VALUE 4.

78 X91-ATT-VOLUME-LABEL VALUE 8.

78 X91-ATT-SUB-DIRECTORY VALUE 16.

78 X91-ATT-ARCHIVED VALUE 32.

For example COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY + X91-ATT-ARCHIVED will return, Normal, Read-only and Archived files or any files with 1 or more of these attributes.

Note that this field is only used on Windows based systems.

X91-IGNORE-HID-SYS

Set this flag to '1' (the default) to indicate that files with both the Hidden and System attributes are to be ignored from the result set. These files typically are reserved for operating system special usage.

1 - ignore hidden+system

0 - do not check the hidden or system attribute

X91-IGNORE-DIRS

Set this flag to '1' (the default) to indicate that sub-directories are to be ignored from the result set.

1 - ignore sub-directories

0 - return sub-directories that match the naming and attributes specified.

X91-IGNORE-FILES

Set this flag to '1' (not the default) to indicate that normal files are to be ignored from the result set. The default value of '0' indicates that files are to be included.

1 - ignore files

0 - return files that match the naming and attributes specified.

Note on Unix systems this flag must be set to '1' to indicate that folders are required as the file attributes defined in X91-ATTRIN are not used.

X91-IGNORE-DOT-DOT

Set this flag to '1' (the default) to indicate that directories with the special '.' and '..' names are to be ignored from the result set. These directories have special meaning to the operating system and are generally not required.

1 - ignore '.' and '..'

0 - allow '.' and '..' directory names to be returned

X91-GET-DATETIME

Set this flag to '1' (not the default) to indicate that the date and time that the file was last updated is to be unpacked into an easy-to-use format.

1 - unpack date and time

0 - do not unpack the date and time fields

Output parameters

X91-STATUS

This indicates the status of the X91-SCAN-DIRECTORY function.

0 - OK (more files can be returned)

1 - End of file list (use the X91-SCAN-COMPLETE function)

2 - Error (use the X91-SCAN-COMPLETE function)

X91-FILEOUT

This field contains a single matched filename. Note that this filename does not contain any path.

X91-SIZE

This field contains the disk file size in bytes of the matched file.

X91-DATE

The date that the file was created in a packed format.

Note that if you set the value X91-GET-DATETIME to 1 the field X91-DATETIME-DATE will be populated in an easy-to-use format (see below).

X91-TIME

The time that the file was created in a packed format.

Note that if you set the value X91-GET-DATETIME to 1 the field X91-DATETIME-TIME will be populated in an easy-to-use format (see below).

X91-ATTROUT

This contains the logical OR of the file attribute. To make this easier to process in you program you can use on or more of the following X91-ATO logical fields.

88 X91-ATO-READ-ONLY.

88 X91-ATO-HIDDEN.

88 X91-ATO-SYSTEM.

88 X91-ATO-VOLUME-LABEL.

88 X91-ATO-SUB-DIRECTORY.

88 X91-ATO-ARCHIVED.

For example if you want to test whether the returned file is Read-only or Hidden then you can include the statement:

IF X91-ATO-READ-ONLY OR X91-ATO-HIDDEN

X91-DATETIME-DATE

The date that the file was last updated in CCYYMMDD format.

This field is only populated when you set the value X91-GET-DATETIME to 1.

X91-DATETIME-TIME

The time that the file was last updated in HHMMSS format. Note that the second field (SS) will only have even numbered seconds (0,2,4,6,..., 56, 58).

This field is only populated when you set the value X91-GET-DATETIME to 1.

Sample code

The following sample code performs the following:

1. Retrieves the default data path of the current company

2. Builds a wildcard matching *.idx in the data path

3. Scans the directory for files that match

4. For each file get the current disk file size in bytes

**********************************************

** Path from GET-STD-SYSPRO-PATH function **

**********************************************

01 PATH-NAM PIC X(255).

01 PATH-LEN PIC X COMP-X.

*

****************************************

** General work fields for routines **

****************************************

01 FILE-PATTERN PIC X(255).

* File name with wildcard

01 MATCHED-FILE PIC X(255).

* Single file name (no path)

01 MATCHED-SIZE PIC X(255).

* Size in bytes of file

01 CONTINUE-LOOP PIC X.

* Continue looping (Y,N)

*

** Determine default data directory in current company

MOVE IM0-PATH TO WW-FILE-NUM.

PERFORM GET-STD-SYSPRO-PATH.

MOVE WW-DIR-NAM TO PATH-NAM.

MOVE WW-DIR-LEN TO PATH-LEN.

*

** Append '*.idx' to the data path

MOVE PATH-NAM TO FILE-PATTERN.

MOVE "*.idx" TO FILE-PATTERN(PATH-LEN:).

*

** Process all files that match pattern

PERFORM PROCESS-FILE-PATTERN.

*

GO TO ENDJOB.

*

***************************************************************

** Scan data directory looking for *.idx files **

** Matches normal, read-only and archived file attributes **

** Input : FILE-PATTERN Path of file including wildcard **

***************************************************************

PROCESS-FILE-PATTERN.

PERFORM PROCESS-FILE-1 THRU PROCESS-FILE-END.

PROCESS-FILE-1.

PERFORM X91-SCAN-INITIALIZE.

COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY +

X91-ATT-ARCHIVED.

MOVE FILE-PATTERN TO X91-FILEIN.

FIND-NEXT.

PERFORM X91-SCAN-DIRECTORY. *> Get first/next file

IF X91-STATUS = ZERO

MOVE X91-FILEOUT TO MATCHED-FILE

PERFORM PROCESS-MATCHED-FILE

IF CONTINUE-LOOP = "Y"

GO TO FIND-NEXT

ELSE

PERFORM X91-SCAN-TERMINATE-EARLY.

PERFORM X91-SCAN-COMPLETE.

*

PROCESS-FILE-END.

*

*

************************************************************

** Process single file in data directory **

** Input : MATCHED-FILE File name (without path) **

** Output : CONTINUE-LOOP Y - Yes **

************************************************************

PROCESS-MATCHED-FILE.

PERFORM PROCESS-MATCH-1 THRU PROCESS-MATCH-END.

PROCESS-MATCH-1.

*

** Example code to get file size

MOVE PATH-NAM TO WW-FILE-NAME.

MOVE MATCHED-FILE TO WW-FILE-NAME(PATH-LEN:).

PERFORM CHECK-FILE-EXISTS.

MOVE NUM TO MATCHED-SIZE.

MOVE "Y" TO CONTINUE-LOOP.

PROCESS-MATCH-END.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

Spacey file names, X91-SCAN-INITIALIZE, X91-SCAN-DIRECTORY, X91-SCAN-TERMINATE-EARLY, X91-SCAN-COMPLETE, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, SET-DIRECTORY-ON-SERVER, GET-DIRECTORY-ON-SERVER


Reindexing

SYSPRO SDK

File handling

Reindexing C-ISAM Files Utility

Introduction

The Reindexing utility is a program that can be run from the SYSPRO menu that enables one or more C-ISAM files to be reindexed.

Why does SYSPRO need a Reindexing Utility?

When setting up a SYSPRO company there is a parameter that defines the data storage as C-ISAM or SQL based. The C-ISAM based companies store their data in C-ISAM format. This is a traditional format where each Indexed file consists of 2 physical operating system files.

When setting up a company as SQL Server based there are still some data files that will remain in a C-ISAM format. Therefore reindexing is still required even for a SQL Server based company. Note that the files reindexed in this case are significantly reduced from the requirements of a C-ISAM based system.

There are 2 main reasons for re-indexing a C-ISAM file:

  • C-ISAM files mark deleted records as logically deleted and will re-use the record when new items are inserted, however if many records are inserted into a data file and then most of them are deleted, reindexing the file can dramatically reduce the amount of disk space consumed by the file. Occasional reindexing can ensure that excessive disk storage is not being consumed by the logically deleted records.

  • If a system failure occurs, either at the client or server end of the network, then the index portion of the data file can become corrupted or 'out of sync' with the data portion. This can lead to data not being available or spurious errors when using programs that access the data. Reindexing these files can be used to rebuild the index to ensure it’s consistency with the data portion.

The Structure of a C-ISAM file

Each C-ISAM Indexed file consists of 2 physical operating system files.

  1. The data portion has a .DAT extension on Windows and no extension on Unix.

  2. The index portion has a .IDX extension on Windows and a .idx extension on Unix.

The data portion contains only data - there is no indexing information. Each record is a fixed length and contains an end of record marker of a line feed (X”0A”). If a record is marked as logically deleted then the data may or may not exist but the end of record marker is changed to a null (X”00”).

The index portion contains a key structure with pointers to the data portion. This information includes the primary key position and length together with a definition of any alternate keys. When a C-ISAM indexed file is opened the record length, primary key length and alternate key details are verified and if found to be inconsistent an error code 39 is generated. Index files are stored in a compressed format and cannot generally be viewed.

How is a File Reindexed?

The reindex process consists of opening the data portion of an indexed file (the index portion may be missing or corrupted). This requires accessing a sequential file one character longer than the record length. This extra character is used to identify the end of record marker.

The reindex program builds a new file with the correct configuration for the format of the C-ISAM file. A temporary file name is generated and the file opened for output.

As each record in the data portion of the file is read, the end of record marker is tested. If this is a logically deleted record then the next record in the data portion can be read. If the record is valid then the data is written to the new indexed file.

When the end of file is reached the new indexed file is closed and both data and indexed portions copied back to the original file name.

What Options are provided?

Reindexing can be a lengthy process, especially for very large files. In addition it is often required to run the process after hours as no-one else can be using the data files whilst they are being reindexed. Therefore the reindex program has several options to allow unattended or low attendance usage. These options include what to do if problems are encountered and logging the reindexing process so that it can be reviewed later.

In addition when files are being reindexed no-one else can be using the files. Several options to assist in verifying that no-one else is using the files and preventing their subsequent usage.

Options include:

  • Allow selection of one, several or all files for a company.

  • Allow a common selection of files to be stored and subsequently re-selected

  • Provide default actions when any problem occurs

  • Provide tick over options to prevent excessive screen refreshing (and improve performance on Client/Server systems)

  • Provide the ability to record and view/print a log file of all reindexing performed

  • Allow viewing who is using the data files in the company and optionally preventing further usage until the reindexing has completed.

The ability to run the reindexing totally unattended is provided. This requires a file name specifying the list of files to be reindexed. It requires no operator input and exits SYSPRO on completion.

Max C-ISAM Files Sizes

The maximum C-ISAM file size supported is 1GB on Windows and approximately 4GB on Unix (when using Server Express). If any file being reindexed is within 90% of it's maximum you will be warned after the reindex has completed and a message will be printed on the output log. Note that on Unix based systems you may need to tune the kernel or set the ULIMIT to reach this maximum.

The following maximum C-ISAM files sizes were verified during July 2010.

Operating System | Max file size
Windows 2000 (all versions) | 1,073,741,000 bytes (1GB)
Unix/Linux/AIX (all versions) | 4,000,000,000 bytes (approx 4GB)

IMPFIL.IMP

The files available to be reindexed are defined in the file IMPFIL.IMP.

The definition of each file includes the file name, record length, primary and alternate key definitions. From this information the end-user can be prompted for a list of files and, when required, the selected files reindexed. Note that for SQL based companies only a small subset of the entire system files are stored as C-ISAM.

Reindexing non-standard files

In addition to the standard SYSPRO C-ISAM data files, user-defined third party files can be reindexed using this system. This includes user-files generated using the Report Writer.

The file CUSFIL.IMP in a custom program directory can be provided for this purpose. It’s format should be similar to a standard IMPFIL.IMP file. This file should be stored in the location defined by the System Setup program, Other Paths Tab, Customized directories – program directory field.

See also

IMPFIL.IMP


Data Dictionary

Introduction

The Data dictionary is a core component of SYSPRO. It contains a complete definition of the data structures for both C-ISAM and SQL format data. This information includes all the files, fields, keys and comments traditionally held in the Record Layouts. In addition to C-ISAM information, SQL Server specific information is held – this includes Table and Column names that do not normally form part of C-ISAM based Record Layouts.

The Data Dictionary system consists of a set of data files shipped as part of SYSPRO that contain the standard SYSPRO data definitions together with a Data Dictionary Manager that is a set of programs that allows import, export and viewing of the Data Dictionary definition.

See the following topics for more information about the Data Dictionary.

Data Dictionary Overview

Data Dictionary Import

Data Dictionary Export

Data Dictionary Conventions

Record Layout

See also

Reindexing


Shared Inventory Files

SYSPRO Companies

Each SYSPRO company has a separate set of physical data.

ISAM companies use the company id as the prefix to each file name. For example the Customer master file (ARSMST) has the following files for company '0':

0ARSMST.DAT

0ARSMST.IDX

and the following files for company '1':

1ARSMST.DAT

1ARSMST.IDX

SQL companies use a separate database for each company. For example company 0's tables could reside in a database called 'Company0' and company 1's tables could reside in a database called 'Company1'.

This is how the vast majority of SYSPRO files/tables are stored.

Inventory tables

The inventory control module allows it's stock items to be 'shared' across companies. This is enabled by allowing you to define a shared inventory id that is to be used (instead of the current company id).

This is easiest explained with an example. Suppose you have two SYSPRO companies - company 0 and company 1. You can set the inventory shared id to '0' for both companies. This means that when you are logged in to company '0' the software will be accessing the inventory master file (INVMST) as:

0INVMST.DAT

0INVMST.IDX

and also that when you are logged in to company '1' you will also be accessing the same files. In fact there will not be any files named 1INVMST.DAT or 1INVMST.IDX.

Similarly when using a SQL Server environment both SQL companies will access the inventory master (InvMaster) table in the 'Company0' database. Note that in this case there will be a table called 'InvMaster' in the 'Company1' database but it will not be accessed - however you must not remove this dummy (empty) table.

Which files use the shared inventory id?

Apart from the files in the Inventory Control module a number of other modules also use the shared inventory id. In addition some modules have some exceptions where files do/do not use the shared inventory id.

The following table lists this information:

Prefix | Description | Comments
INV | Inventory Control | All inventory files except INVJNC, INVJND, INVDIS
BOM | Bill of Materials | Also ARCBOM
IOP | Inventory Optimization |
ECC | Engineering Change Control |
CFG | Product Configurator |
GTR | Goods in Transit |
LCT | Landed Cost Tracking | Only LCT files named LCTBIL, LCTELE, LCTTAR, LCTCAL, LCTCON, LCTROU, LCTEXC use the inventory shared id
LOT | Lot Traceability |
WMS | Warehouse management |
QMS | Quality Management |

There is a function called CHECK-SHARED-TABLE that allows you to pass a table name and the return information includes whether the table is shared and also which company it is shared with.

See also

Data Dictionary Overview, SQL Server and ISAM Differences, CHECK-SHARED-TABLE


SYSPRO 6.1 SP1 Database Changes

This topic covers the database changes between SYSPRO 6.1 and SYSPRO 6.1 SP1. It includes both SQL Server and C-ISAM changes.

Steps to convert to SYSPRO 6.1

Install the SYSPRO 6.1 software.

When you first log into each company the SYSPRO 6.1 conversion wizard will be invoked.

This wizard will handle the data file conversion for both SQL Server and C-ISAM based companies. There are various types of conversion required. The effect of each conversion is summarised below. A more detailed list of new tables, new columns and any other conversions is provided at the end of this topic.

Conversion type | SQL Server implications | C-ISAM implications
Column/field changed in size | Wizard alters the column size | Wizard performs a data file conversion to reorganize the file layout making space for the larger column

Details of data conversions

The following details the database changes for SYSPRO 6.1 SP1.

Change of Datatype

The following fields have been enlarged for SYSPRO 6.1 SP1.

Table name | ISAM file | Description | Field changed to 2.3 from 2.2
AdmTax | ADMTAX | Admin Tax Master | CurTaxRate PrvTaxRate
AdmTaxHistory | ADMTXH | Admin Tax History | PrvTaxRate
AdmWithholdingTax | ADMWTH | Admin Withholding Tax Rates | CurTaxRate
ApInvoice | APSINV | AP Supplier Invoice Detail | WithTaxRate
ApPayRunDet | APSPRD | AP Payment Run Detail | WithTaxRate
ApWithholdTax | APSWTH | AP Withholding Tax Details | WithTaxRate
ArPermReprint | ARSREP | AR Permanent Entries Invoice Reprint | TaxRate FstTaxRate
ArTrnGst | ARSSTC | AR Sales Transaction Canadian GST | GstRate
IntEdiInvDet | INTDET | EDI Invoice Detail | TaxRate
SalGstCanSum | SALGSS | SA Canadian GST Summary | CurGstRateA CurGstRateB CurGstRateC CurGstRateD CurGstRateE CurGstRateF CurGstRateG CurGstRateH
SalGstCanDet | SALGST | SA Canadian GST Detail | TaxRate

Columns added to existing tables

There is one new column added for SYSPRO 6.1 SP1. You can use the Data Dictionary Viewer program (DDSBFI) to view more information about the column definition.

Table and column name | Datatype
AdmTax.TaxRateDecimals | decimal(1,0)

See also

What's new about SYSPRO 6.1 SP1


SYSPRO 6.1 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 010 SP2 and SYSPRO 6.1. It includes both SQL Server and C-ISAM changes.

Conversion process

There is a significant number of database changes for SYSPRO 6.1.

It is recommended that before you install SYSPRO 6.1 and run the data conversion wizard you download and run the SYSPRO 6.1 readiness program (IMPR61) is SYSPRO 6.1 Issue 010 SP2. This program will report on any issues that need to be resolved before you install SYSPRO 6.1. The areas of particular interest are any GL Integration journal and distribution files. By running this Readiness Program first you can be sure that when you install SYSPRO 6.1 and run the data conversion wizard that there will be no problems.

The Data Migration Wizard will take you through the process of converting your SYSPRO 6.0 Issue 010 SP2 format data files to SYSPRO 6.1. This conversion wizard converts both C-ISAM and SQL Server based companies.

Note that the SYSPRO 6.1 data conversion wizard can only be used to convert SYSPRO 6.0 Issue 010 SP2 format companies to issue SYSPRO 6.1.

Steps to convert to SYSPRO 6.1

Install the SYSPRO 6.1 software.

When you first log into each company the SYSPRO 6.1 conversion wizard will be invoked.

This wizard will handle the data file conversion for both SQL Server and C-ISAM based companies. There are various types of conversion required. The effect of each conversion is summarised below. A more detailed list of new tables, new columns and any other conversions is provided at the end of this topic.

Conversion type | SQL Server implications | C-ISAM implications
New table/file | Wizard adds table, column and key definitions | None - SYSPRO application programs create the new file when required
New column/field (using FILLER in C-ISAM file layout) | Wizard adds new column | None - SYSPRO application programs reference new field when required
New column/field (record length increased in C-ISAM file layout) | Wizard adds new column | Wizard performs a data file conversion to create the new format file
New index required | Wizard adds new index | Wizard re-indexes file to add new index
Column/field changed in size | Wizard alters the column size | Wizard performs a data file conversion to reorganize the file layout making space for the larger column
Existing table/file split or reorganized into different files | Wizards adds new tables and moves data from original location to new location | Wizards adds new files and moves data from original location to new location
ISAM files being migrated to SQL | Wizard adds new table and moves data from ISAM to SQL | None - files only migrated to SQL Server for ISAM based systems

Conversions

The data conversions are required due to the large number of new features added to this version of SYSPRO. Part of the conversion process is dedicated to the following functions:

Assets Register

The Assets Register has been significantly enhanced for SYSPRO 6.1 and this has required a significant upgrade to the table structures used by this module. This includes information being split from the AssetMaster table into many sub tables. If you are developing features around this module it is suggested that you study the new Assets Register data structures.

General Ledger Integration

The General Ledger Integration process has been significantly enhanced for SYSPRO 6.1 and this has required a significant change to the table structures used by this feature. This includes consolidating previous distribution and journal files into a single set of data files.

Inventory Document files Migrated to SQL

On SQL Server based systems the Inventory Document files are now stored in SQL Server tables. This provides benefits such as unlimited table size for SYSPRO 6.1. This has no effect on ISAM based systems.

AP Payment Cycle

The AP Payment cycle was enhanced several SYSPRO 6.0 versions ago. However until now we have supported the previous legacy payment cycle logic. From SYSPRO 6.1 only the 'newer' AP Payment Cycle is supported. You must not have any 'pending' legacy payment cycle outstanding before running the SYSPRO 6.1 data conversion wizard. Also the data conversion wizard will remove the legacy tables and files.

During the conversion process a log will be output to an ASCII text file in the work folder with the name ?IMPC6E.DAT - where ? is the company id. This can be useful to view a log of the process and to determine what occurred if the conversion fails for any reason.

Once the conversion has successfully completed the company control file (ADMCTL) will be updated to the latest version number so that you can log in as normal.

Details of data conversions

The following details the database changes for SYSPRO 6.1.

Files That Are No Longer Required

The following files were used in previous releases but have been migrated to other tables or are no longer required (e.g. the Legacy AP Payment Cycle) and will be removed during the conversion process. On SQL Server based systems these tables will be dropped during the conversion process.

Table name | ISAM file | Description | Reason for deletion
ApListChDet | APSCHD | AP Supplier Check Print Detail | Legacy AP payment cycle
ApChIssued | APSCHI | AP Checks Issued | Legacy AP payment cycle
ApListChHdr | APSCHH | AP Supplier Check Print Header | Legacy AP payment cycle
ApGlExpAp | APSDEX | AP Supplier Expense Distribution | Legacy GL integration
ArDiscDrCrDetail | ARSDCE | AR Discount Cr/Dr Notes Detail |
{not applicable} | APSDCH | AP Supplier Dummy Check Seq File | Legacy AP payment cycle
ApReleasePtr | APSRPT | AP Release Pointer Sequential File | Legacy AP payment cycle
ArGlPayments | ARSPYD | AR Customer Payment Distribution | Legacy GL integration
ArGlSales | ARSSAD | AR Customer Sales Distribution | Legacy GL integration
AssetControl | ASSCTL | Asset Control | Legacy GL integration
AssetDeprEnt | ASSDPR | Asset Depreciation Calculation Details | Legacy GL integration
AssetEntries | ASSENT | Asset Entries | Legacy GL integration
AssetGroupOld | ASSGRO | Asset Group (Issue 008 Format) | Legacy GL integration
AssetHistory | ASSHST | Asset History | Legacy GL integration
AssetMasterOld | ASSMSO | Asset Master (Issue 008 Format) | Legacy GL integration
GenEntriesCtl | GENENC | GL Entries Group Control | Legacy GL integration
GenEntriesDetail | GENEND | GL Entries Group Detail | Legacy GL integration
InvDistribution | INVDIS | Inventory Distribution | Legacy GL integration
WipDistrLab | WIPPBL | WIP Part Billing Labor Distribution | Legacy GL integration

Also note that after INVDOC, INVDOI, INVDOS and INVDOX have been migrated from ISAM files to SQL Server tables they will be physically deleted from ISAM based systems.

New Tables

The following files/tables are new for SYSPRO 6.1. On C-ISAM based systems these files will be created as and when necessary. On SQL Server based systems these tables will be created during the conversion process.

Table name

ISAM file

Description

AdmAnalyticsCtl

AdmTaxReturn

ApPayRunChkDet

ApInvoiceRegPo

ArInvoiceReference

ArTrnTaxUkVat

AssetControlAlt

AssetControlBv

AssetControlTax

AssetDepnAlt

AssetDepnBv

AssetDeprVarAnnual

AssetDeprVarPeriod

AssetDepnTax

AssetEntriesAlt

AssetEntriesBv

AssetEntriesTax

AssetHistoryAlt

AssetHistoryBv

AssetHistoryQty

AssetHistoryTax

BomSchedGroupDet

BomSchedGroup

CshFlowCollector

CshFlowProjDates

CshFlowDetails

CshFlowInclusion

CshFlowModel

CshFlowValues

GenJnlTempSplit

GenShares

InvDocument

InvInspectDoc

InvDocumentSerial

InvInspectDocSer

InvMasterUom

InvPhysicalUnit

InvSite

InvSiteType

InvUom

InvWhArea

InvWhBin

IopDeliveryPerf

IopForeSnapshot

IopForeSnapHead

IopSelectionList

IopArchiveStockLvl

IopDraftStockLvl

IopLvlAmendJnl

IopStockLevel

IopMovements

IopPolicyAmendJnl

IopPolicies

IopSupplyCon

IopSelSetAmendJnl

IopSelectionSet

IopSupplyMethod

IopSalesPerf

MrpDetailPegging

MrpSplitLabAll

MrpStockLevel

MrpMpsDetPegging

MrpSugSplitLabAll

PrjHierarchyXref

QmsElement

QmsInspectDetail

QmsInspectElement

QmsInspectElemList

QmsInspectDtMetric

QmsInspection

ReqGroupActualUse

ReqGroupBudgets

ReqGroupAuthority

ReqGroupActualQty

ReqGroup

SalSalesTaxUkVat

SwsAction

SwsActionDetail

SwsMessages

TblSaSupplUnits

TpmPromoDetTrans

WipLabJnlStat

WmsBinContainer

WmsBinContainerTyp

WmsBinType

WmsBinStock

WmsStorageCond

WmsStorageHazard

WmsStorageSecurity

ADMSAN

ADMTXR

APSPCK

APSRPO

ARSINX

ARSSTU

ASSCAL

ASSCBV

ASSCTX

ASSDAL

ASSDBV

ASSDPA

ASSDPP

ASSDTX

ASSEAL

ASSEBV

ASSETX

ASSHAL

ASSHBV

ASSHQT

ASSHTX

BOMSGD

BOMSGH

CSHCOL

CSHDAT

CSHDET

CSHINC

CSHMOD

CSHVAL

GENJNT

GENSHR

INVDOC

INVDOI

INVDOS

INVDOX

INVMSU

INVPHU

INVSIT

INVSTP

INVUOM

INVWAR

INVWBN

IOPDEP

IOPFSD

IOPFSH

IOPLST

IOPLVA

IOPLVD

IOPLVJ

IOPLVL

IOPMOV

IOPPOJ

IOPPOL

IOPSCO

IOPSEJ

IOPSEL

IOPSMT

IOPSOP

MRPDET

MRPLSP

MRPLVL

MRPMDT

MRPSSP

PRJXRF

QMSELM

QMSIND

QMSINE

QMSINL

QMSINM

QMSINS

REQGRA

REQGRB

REQGRP

REQGRQ

REQUSG

SALTAU

SWSACD

SWSACT

SWSMSG

TBLEUU

TPMPTN

WIPJNS

WMSBCN

WMSBCT

WMSBNT

WMSBSK

WMSCON

WMSHAZ

WMSSEC

Admin Analytics Filter Control

Tax Return Detail

AP Payment Run Check Detail

AP Invoice Registration Purchase Orders

AR Invoice Reference

AR Sales Transaction Tax Summary UK VAT

Asset Control Alternate Value

Asset Control Book Value

Asset Control Tax

Asset Depreciation Alternate Value

Asset Depreciation Book Value

Asset Depreciation Varying Annually

Asset Depreciation Varying per Period

Asset Depreciation Tax

Asset Entries Alternate Values

Asset Entries Book Value

Asset Entries Tax

Asset History Alternate Value

Asset History Book Value

Asset History Quantity

Asset History Tax Value

BOM Scheduling Group Detail

BOM Scheduling Group Header

Cash Flow Collector

Cash Flow Projection Dates

Cash Flow Details

Cash Flow Inclusions

Cash Flow Models

Cash Flow Values

GL Journal Template Split

GL Shareholding

Inventory Document Print Transaction

Inventory Inspection Document

Inventory Document Print Serial Trans

Inventory Inspection Document Serials

Inventory Master UOM

Inventory Physical Unit

Inventory Site

Inventory Site Type

Inventory Units of Measure

Inventory Warehouse Area

Inventory Bin

IO Delivery Performance

IO Forecast Snapshot

IO Forecast Snapshot Header

IO Selection List

IO Archived Stock Level

IO Draft Stock Level

IO Draft Stock Levels Amendment Journal

IO Stock Level

IO Movements

IO Policy Amendment Journal

IO Policies For Stock Code Warehouse

IO Supply Constraints

IO Selection Set Amendment Journal

IO Selection Set

IO Supply Method

IO Sales Order Performance

MRP Detail Pegging

MRP Snapshot Labor Allocations Splits

MRP Stock Level

MRP MPS Detail Pegging

MRP Suggested Labor Allocations Splits

P&C Hierachy Posting Cross Reference

Quality Measurement Element

Quality Inspection Detail

Quality Inspection Measurement Element

Quality Inspection Measurement Elem List

Quality Inspection Detail Metric

Quality Inspection

Requisition Group Actual Usage

Requisition Group Budgets

Requisition Group Authority Levels

Requisition Group Actual Quantity Usage

Requisition Group

SA Sales Analysis Tax UK VAT

Workflow Action Description

Workflow Action Detail

Workflow Messages

SA Intrastat Supplementary Units

TPM Promotion Detail Transactions

WIP Labor Journal Status

WMS Bin Container

WMS Bin Container Type

WMS Bin Type

WMS Bin Stock

WMS Storage Conditions

WMS Storage Hazards

WMS Storage Security Code

New C-ISAM Files

The following files are new for SYSPRO 6.1. All of these files always remain in C-ISAM, even on a SQL Server based system. They will be created as and when necessary. Note the Table name column indicates the name by which the C-ISAM file can be referenced in the Report Writer, from ODBC or other technologies.

Table name | ISAM file | Description
AdmSystemAuditLog AdmResourceLock AdmRoleAccess AdmRole AdmRoleProgram AdmTaxReturnPeriod | ADMJNS ADMLCK ADMRLA ADMRLE ADMRLP ADMTXP | Admin System Audit Log Admin Resource Lock Admin Role Access Control Admin Role Admin Role Program Access Admin Tax Return Periods Definition

Change of Datatype

The following fields have either been enlarged for SYSPRO 6.1 or have had their datatype changed..

Table name | ISAM file | Description | Reason for change
ArCustomerBal | ARSBAL | AR Customer Master Balances | SalesValMth(1-26) decimal(12,0) to decimal(14,2)
AssetDepreciation | ASSDEP | Asset Depreciation | AnnualDepnPct decimal(5,2) to decimal(7,4)
CshApPayments | CSHAPD | Cash Book AP Payment Details | Cheque from char(6) to decimal(6,0)
GenJournalDetail | GENJND | GL Journal Detail | Reference from char(9) to char(30)
GenRecJnlDet | GENRJD | GL Recurring Journal Detail | Reference from char(9) to char(30)
GenStdJnlDet | GENSTD | GL Standard Journal Detail | Reference from char(9) to char(30)
RmaMaster | RMAMST | RMA Master | Contact from char(20) to char(40)

Columns added to existing tables

There are a number of new columns added to existing tables for SYSPRO 6.1. The following lists the Table.ColumnName of each new column and it's datatype. You can use the Data Dictionary Viewer program (DDSBFI) to view more information about these column definitions.

Table and column name

Datatype

ApBank.GlExchSeparate

ApBank.GlExchLossCode

ApControl.LowUnpExpJnlYear

ApControl.LowUnpExpJnlMonth

ApControl.LowUnpExpJnl

ApControl.UnpExpJnlYear

ApControl.UnpExpJnlPeriod

ApGlDisburse.GlIntUpdated

ApGlDisburse.GlIntYear

ApGlDisburse.GlIntPeriod

ApGlDisburse.GlJournal

ApIntegrationCtl.GlExchSeparate

ApIntegrationDet.GlExchLossCode

ApJnlSummary.GlIntUpdated

ApJnlSummary.GlIntPrinted

ApJnlSummary.GlIntYear

ApJnlSummary.GlIntPeriod

ApJnlSummary.GlJournal

ApJnlSummary.TrnDate

ApJnlSummary.AddReference

ApSupplier.RemitEmail

ApPayRunDet.WithTaxCode

ApPayRunDet.WithTaxableValue

ArControl.ArUpdYear

ArControl.ArUpdMonth

ArControl.ArUpdJournal

ArControl.SaUpdYear

ArControl.SaUpdMonth

ArControl.SaUpdReg

ArControl.DtUpdYear

ArControl.DtUpdMonth

ArControl.DtUpdReg

ArControl.UnpBdsUpdYear

ArControl.UnpBdsUpdMonnth

ArControl.UnpBdsUpdRegister

ArDiscDrCrDet.Sequence

ArDiscDrCrDet.CurrencyValue

ArDiscDrCrDet.PostCurrency

ArDiscDrCrDet.ConvRate

ArDiscDrCrDet.MulDiv

ArDiscDrCrDet.AccountCur

ArDiscDrCrDet.AccConvRate

ArDiscDrCrDet.AccMulDiv

ArDiscDrCrDet.TriangCurrency

ArDiscDrCrDet.TriangRate

ArDiscDrCrDet.TriangMulDiv

ArIntegrationCtl.GlExchSeparate

ArIntegrationDet.GlExchLossCode

ArCshJnlDet.AdjustmentGLCode

ArCshJnlDet.CashGLCode

ArCshJnlDet.PaymentGLCode

ArCshJnlDet.DepositGLCode

ArCshJnlDet.WthTaxGLCode

ArCshJnlDet.TaxGLCode

ArCshJnlDet.DiscountGLCode

ArCshJnlDet.SalesCtlTaxGLCode

ArCshJnlDet.BankChargeGLCode

ArCshJnlDet.AdjustmentAnaEntry

ArCshJnlDet.CashAnaEntry

ArCshJnlDet.PaymentAnaEntry

ArCshJnlDet.DepositAnaEntry

ArCshJnlDet.WthTaxAnaEntry

ArCshJnlDet.TaxAnaEntry

ArCshJnlDet.DiscountAnaEntry

ArCshJnlDet.SlsCtlTaxAnaEntry

ArCshJnlDet.BankChargeAnaEntry

ArCshJnlDet.GlIntUpdated

ArCshJnlDet.GlIntPrinted

ArCshJnlDet.GlIntYear

ArCshJnlDet.GlIntPeriod

ArCshJnlDet.GlJournal

ArInvoice.DiscBal

ArCustomer.UkVatFlag

ArCustomer.UkCurrency

ArTrnDetail.TransactionGLCode

ArTrnDetail.DiscountGLCode

ArTrnDetail.CostGLCode

ArTrnDetail.GlIntUpdated

ArTrnDetail.GlIntPrinted

ArTrnDetail.GlIntYear

ArTrnDetail.GlIntPeriod

ArTrnDetail.GlJournal

ArTrnDetail.ControlType

ArTrnDetail.TranAnalysisEntry

ArTrnDetail.DscAnalysisEntry

ArTrnDetail.CstAnalysisEntry

ArTrnSummary.DispatchAccount

ArTrnSummary.DisAnalysisEntry

ArTrnSummary.DispatchAmount

ArTrnSummary.WarehouseAccount

ArTrnSummary.WhAnalysisEntry

ArTrnSummary.WarehouseAmount

ArTrnSummary.BranchSalesAccount

ArTrnSummary.BrSalesAnaEntry

ArTrnSummary.BranchSalesAmount

ArTrnSummary.BranchCostAccount

ArTrnSummary.BrCstAnalysisEntry

ArTrnSummary.BranchCostAmount

ArTrnTax.UkVatFlag

ArInvoicePay.Branch

AssetControl.HistEntPeriodsTx

AssetControl.HistEntPrdsAlt1

AssetControl.HistEntPrdsAlt2

AssetControl.HistEntPrdsAlt3

AssetControl.HistEntPrdsAlt4

AssetControl.HistEntPrdsAlt5

AssetControl.HistEntPrdsAlt6

AssetControl.HistEntPrdsAlt7

AssetControl.HistEntPrdsAlt8

AssetControl.HistEntPrdsAlt9

AssetControl.HistEntPrdsAlt10

AssetControl.HistoryYearsBv

AssetControl.HistoryYearsTax

AssetControl.HistoryYearsAlt1

AssetControl.HistoryYearsAlt2

AssetControl.HistoryYearsAlt3

AssetControl.HistoryYearsAlt4

AssetControl.HistoryYearsAlt5

AssetControl.HistoryYearsAlt6

AssetControl.HistoryYearsAlt7

AssetControl.HistoryYearsAlt8

AssetControl.HistoryYearsAlt9

AssetControl.HistoryYearsAlt10

AssetControl.ValuationHead4

AssetControl.ValuationHead5

AssetControl.ValuationHead6

AssetControl.ValuationHead7

AssetControl.ValuationHead8

AssetControl.ValuationHead9

AssetControl.ValuationHead10

AssetControl.DateConvDef

AssetControl.BvConvention

AssetControl.TaxConvention

AssetControl.AltConvention1

AssetControl.AltConvention2

AssetControl.AltConvention3

AssetControl.AltConvention4

AssetControl.AltConvention5

AssetControl.AltConvention6

AssetControl.AltConvention7

AssetControl.AltConvention8

AssetControl.AltConvention9

AssetControl.AltConvention10

AssetControl.TaxBasis

AssetControl.AltBasis1

AssetControl.AltBasis2

AssetControl.AltBasis3

AssetControl.AltBasis4

AssetControl.AltBasis5

AssetControl.AltBasis6

AssetControl.AltBasis7

AssetControl.AltBasis8

AssetControl.AltBasis9

AssetControl.AltBasis10

AssetControl.NextAsset

AssetControl.NextCapex

AssetDepreciation.DateConvention

AssetDepreciation.StatGlCode

AssetDepreciation.NumberOfYears

AssetDepreciation.ThruputEul

AssetDepreciation.VaryingAnniversary

AssetDistReg.GlIntUpdated

AssetDistReg.GlIntYear

AssetDistReg.GlIntPeriod

AssetDistReg.GlJournal

AssetEntries.SuspendFlag

AssetEntries.AssetEntryQty

AssetGroup.MinTax

AssetGroup.MinAlt1

AssetGroup.MinAlt2

AssetGroup.MinAlt3

AssetGroup.MinAlt4

AssetGroup.MinAlt5

AssetGroup.MinAlt6

AssetGroup.MinAlt7

AssetGroup.MinAlt8

AssetGroup.MinAlt9

AssetGroup.MinAlt10

AssetMaster.DepPrdYearSold

AssetMaster.PurchasePeriod

AssetMaster.PurchaseYear

AssetMaster.DisposedFlag

AssetMaster.AltFlag1

AssetMaster.AltFlag2

AssetMaster.AltFlag3

AssetMaster.AltFlag4

AssetMaster.AltFlag5

AssetMaster.AltFlag6

AssetMaster.AltFlag7

AssetMaster.AltFlag8

AssetMaster.AltFlag9

AssetMaster.AltFlag10

AssetMaster.DisposalReason

BomCoProducts.QtyPerEnt

BomAmendmentJnl.OldQtyPerEnt

BomAmendmentJnl.OldScrapQtyEnt

BomAmendmentJnl.OldFixedQtyPerEnt

BomAmendmentJnl.NewQtyPerEnt

BomAmendmentJnl.NewScrapQtyEnt

BomAmendmentJnl.NewFixedQtyPerEnt

BomStructure.QtyPerEnt

BomStructure.ScrapQuantityEnt

BomStructure.FixedQtyPerEnt

BomOperations.IRunTimeEnt

BomOperations.ITimeTakenEnt

BomOperations.IStartupQtyEnt

BomOperations.IQuantityEnt

BomOperations.OperYieldQtyEnt

BomOperations.TransferQtyPctEnt

BomOperations.MaxOpSpan

BomOperations.OpSlack

BomOperations.AllowOpSplit

CrmAccount.Supplier

CrmActivity.UserField1

CrmActivity.UserField2

CrmActivity.UserField3

CshTransactionsBal.CbTrnBal3

CshTransactionsBal.CbTrnForBal3

CshControl.UnpGlIntPrintYear

CshControl.UnpGlIntPrintMonth

CshControl.UnpGlIntPrintJnl

CshJnlCtl.GlIntUpdated

CshJnlCtl.GlIntPrinted

CshJnlCtl.GlIntYear

CshJnlCtl.GlIntPeriod

CshJnlCtl.GlJournal

EccCoProducts.QtyPerEnt

EccAmendmentJnl.OldQtyPerEnt

EccAmendmentJnl.OldScrapQtyEnt

EccAmendmentJnl.OldFixedQtyPerEnt

EccAmendmentJnl.NewQtyPerEnt

EccAmendmentJnl.NewScrapQtyEnt

EccAmendmentJnl.NewFixedQtyPerEnt

EccOperations.IStartupQtyEnt

EccOperations.IQuantityEnt

EccOperations.IRunTimeEnt

EccOperations.ITimeTakenEnt

EccOperations.OperYieldQtyEnt

EccOperations.TransferQtyPctEnt

EccOperations.MaxOpSpan

EccOperations.OpSlack

EccOperations.MaxOpDelay

EccOperations.AllowOpSplit

EccStructure.QtyPerEnt

EccStructure.ScrapQuantityEnt

EccStructure.FixedQtyPerEnt

GenCopyMaster.RetEarnsAccount

GenCopyMaster.InterestAccount

GenCopyTrans.Reconciled

GenCopyTrans.TransactionDate

GenCopyTrans.AlternateRate

GenJournalCtl.JournalSource

GenJournalCtl.Type

GenJournalCtl.PostDate

GenJournalCtl.SourceJournal

GenJournalDetail.Source

GenJournalDetail.Type

GenJournalDetail.SourceAp

GenJournalDetail.SourceJournal

GenJournalDetail.ModifiedFlag

GenJournalDetail.AddReference2

GenJournalDetail.CommitmentFlag

GenJournalDetail.TransactionDate

GenMaster.RetEarnsAccount

GenMaster.TaxAccount

GenMaster.InterestAccount

GenSection.RetEarnsAccount

GenSection.TaxAccount

GenSection.InterestAccount

GenTransaction.Reconciled

GenTransaction.TransactionDate

GenTransaction.AlternateRate

GrnJournal.GlIntUpdated

GrnJournal.GlIntPrinted

GrnJournal.GlIntYear

GrnJournal.GlIntPeriod

GrnJournal.GlJournal

GrnJournal.ControlGlCode

GrnJournal.TransactionAnaEnt

GrnJournal.ControlAnaEntry

GrnJournal.ProductClass

GtrFifoTransfer.LotSerial

GtrFifoTransfer.Version

GtrFifoTransfer.Release

InvCompanyCtl.UnpInvJnlUpdYear

InvCompanyCtl.UnpInvJnlUpdMonth

InvCompanyCtl.UnpInvJnlUpd

InvCompanyCtl.UnpInvDisUpdYear

InvCompanyCtl.UnpInvDisUpdPeriod

InvCompanyCtl.UnpGrnDisUpdYear

InvCompanyCtl.UnpGrnDisUpdPeriod

InvControl.NextStockCode

InvFifoLifo.ReceiptQty

InvFifoLifo.LotSerial

InvFifoLifo.Version

InvFifoLifo.Release

InvJournalCtl.GlIntUpdated

InvJournalCtl.GlIntPrinted

InvJournalCtl.GlIntYear

InvJournalCtl.GlIntPeriod

InvJournalCtl.GlJournal

InvJournalDet.LotSerial

InvMovements.LotSerial

InvMovements.IoProcessedFlag

InvMaster.StorageSecurity

InvMaster.StorageHazard

InvMaster.StorageCondition

InvSerialTrn.UnitCost

InvSerialTrn.Bucket

InvTransFifoLifo.LotSerial

InvTransFifoLifo.Version

InvTransFifoLifo.Release

InvWhControl.WmsActive

InvWhControl.PickLeadHours

InvWhControl.StockTakeUpdate

InvWhControl.NonStockedGl

InvWhControl.State

InvWhControl.CountyZip

InvWhControl.City

IopColInstance.Disaggregate

IopCollectAdjust.LostSaleTrnDate

IopCollectAdjust.LostSaleTrnTime

IopColSelect.SelectionSet

IopConSalesAdjust.LostSaleTrnDate

IopConSalesAdjust.LostSaleTrnTime

IopProxies.Warehouse

IopProxies.ProxyWarehouse

IopSalesReturns.TransCount

IopSalesReturns.Quantity

IopSalesReturns.CostValue

IopSalesReturns.SalesValue

IopSales.TransCount

IopSales.Quantity

IopSales.CostValue

IopSales.SalesValue

IopWarehouse.IdNumber

IopWarehouse.UserField1

IopWarehouse.UserField2

IopWarehouse.UserField3

IopWarehouse.UserField4

IopWarehouse.UserField5

IopWarehouse.UserField6

IopWarehouse.ForeAccuracyDays

IopWarehouse.IntDemandDays

IopWarehouse.IntDemandPct

LotTransactions.UnitCost

LotTransactions.Bucket

MdnDetailCons.SalesOrderDetStat

MdnDetail.SalesOrderDetStat

MdnMaster.DetailStatus

MdnDetailRepCon.SalesOrderDetStat

MdnMasterRepCon.DetailStatus

MdnDetailRep.SalesOrderDetStat

MdnMasterRep.DetailStatus

MrpJobClass.WipCtlGlCode

MrpJobClass.WipInsGlCode

MrpJobClass.WipAutoGlCode

MrpJobClass.WipVarGlCode

MrpCoProducts.QtyPerEnt

MrpCoProducts.QtyToMakeEnt

MrpCoProducts.QtyManufacturedEnt

MrpCoProducts.TotalQtyScrapEnt

MrpJobMaster.QtyToMakeEnt

MrpJobMaster.QtyManufacturedEnt

MrpJobMaster.TotQtyScrappedEnt

MrpJobMaster.GrossQtyEnt

MrpJobAllLab.IStartupQtyEnt

MrpJobAllLab.IQuantityEnt

MrpJobAllLab.IExpUnitRunTimEnt

MrpJobAllLab.ITimeTakenEnt

MrpJobAllLab.QtyScrappedEnt

MrpJobAllLab.TransferQtyPctEnt

MrpJobAllLab.ParentQtyPlanEnt

MrpJobAllLab.OperYieldQtyEnt

MrpJobAllLab.ParIssQtyEnt

MrpJobAllLab.QtyCompletedEnt

MrpJobAllLab.ResourceMask

MrpJobAllLab.SchStartRunDate

MrpJobAllLab.SchStartRunTime

MrpJobAllLab.ScheduledMachine

MrpJobAllLab.AllowOpSplit

MrpJobAllMat.UnitQtyReqdEnt

MrpJobAllMat.QtyIssuedEnt

MrpJobAllMat.QtyBilledEnt

MrpJobAllMat.ScrapQuantityEnt

MrpJobAllMat.NetUnitQtyReqdEnt

MrpJobAllMat.FixedQtyPerEnt

MrpQotOffer.MDiscChanged

MrpQotOperation.IRunTimeEnt

MrpQotOperation.ITimeTakenEnt

MrpQotOperation.IStartupQtyEnt

MrpQotOperation.IBlockQtyEnt

MrpQotOperation.OperYieldQtyEnt

MrpQotOperation.TransferQtyPctEnt

MrpQotOperation.MaxOpSpan

MrpQotOperation.OpSlack

MrpQotOperation.MaxOpDelay

MrpQotOperation.AllowOpSplit

MrpQotSoDetail.SalesOrderDetStat

MrpQotSoDetail.PreactorPriority

MrpQotSoDetail.SalesOrderResStat

MrpQotSoDetail.QtyReservedShip

MrpQotSoMasterHdr.DetailStatus

MrpQotStructure.QtyPerEnt

MrpQotStructure.ScrapQuantityEnt

MrpQotStructure.FixedQtyPerEnt

MrpPoMasterHdr.DeliveryMethod

MrpReqDetail.ApprovedDate

MrpReqDetail.SelectionCode

MrpReqDetail.SelectionType

MrpSugCoProducts.QtyPerEnt

MrpSugCoProducts.QtyToMakeEnt

MrpSugCoProducts.QtyManufacturedEnt

MrpSugCoProducts.TotalQtyScrapEnt

MrpSugWipCtl.LowUnpLabUpdYear

MrpSugWipCtl.LowUnpLabUpdPeriod

MrpSugWipCtl.LowUnpLabUpdJnl

MrpSugWipCtl.LowUnpBillUpdYear

MrpSugWipCtl.LowUnpBillUpdPrd

MrpSugWipCtl.LowUnpBillUpdJnl

MrpSugWipCtl.UnpLabUpdYear

MrpSugWipCtl.UnpLabUpdPeriod

MrpSugWipCtl.UnpBillUpdYear

MrpSugWipCtl.UnpBillUpdPeriod

MrpSugJobMaster.QtyToMakeEnt

MrpSugJobMaster.QtyManufacturedEnt

MrpSugJobMaster.TotQtyScrappedEnt

MrpSugJobMaster.GrossQtyEnt

MrpSugJobAlLab.IStartupQtyEnt

MrpSugJobAlLab.IQuantityEnt

MrpSugJobAlLab.IExpUnitRunTimEnt

MrpSugJobAlLab.ITimeTakenEnt

MrpSugJobAlLab.QtyScrappedEnt

MrpSugJobAlLab.TransferQtyPctEnt

MrpSugJobAlLab.ParentQtyPlanEnt

MrpSugJobAlLab.OperYieldQtyEnt

MrpSugJobAlLab.ParIssQtyEnt

MrpSugJobAlLab.QtyCompletedEnt

MrpSugJobAlLab.ResourceMask

MrpSugJobAlLab.SchStartRunDate

MrpSugJobAlLab.SchStartRunTime

MrpSugJobAlLab.ScheduledMachine

MrpSugJobAlLab.AllowOpSplit

MrpSugJobAlMat.UnitQtyReqdEnt

MrpSugJobAlMat.QtyIssuedEnt

MrpSugJobAlMat.QtyBilledEnt

MrpSugJobAlMat.ScrapQuantityEnt

MrpSugJobAlMat.NetUnitQtyReqdEnt

MrpSugJobAlMat.FixedQtyPerEnt

MrpSoDetail.SalesOrderDetStat

MrpSoDetail.PreactorPriority

MrpSoDetail.SalesOrderResStat

MrpSoDetail.QtyReservedShip

MrpSoMasterHdr.DetailStatus

MrpSugReqDetail.ApprovedDate

MrpSugReqDetail.SelectionCode

MrpSugReqDetail.SelectionType

MrpWipInspect.QtyManufacturedEnt

MrpWipInspect.QtyInspectedEnt

MrpWipInspect.QtyAcceptedEnt

MrpWipInspect.QtyScrappedEnt

MrpWipInspect.QtyReworkedEnt

PorMasterDetail.OrderLineStatus

PorEcReceipts.SupplUnitQty

PorHistReceipt.Version

PorHistReceipt.Release

PorHistReceipt.DeliveryMethod

PorMasterHdr.DeliveryMethod

QotOffer.MDiscChanged

QotOperation.IRunTimeEnt

QotOperation.ITimeTakenEnt

QotOperation.IStartupQtyEnt

QotOperation.IBlockQtyEnt

QotOperation.OperYieldQtyEnt

QotOperation.TransferQtyPctEnt

QotOperation.MaxOpSpan

QotOperation.OpSlack

QotOperation.MaxOpDelay

QotOperation.AllowOpSplit

QotOperation.DetailStatus

QotStructure.QtyPerEnt

QotStructure.ScrapQuantityEnt

QotStructure.FixedQtyPerEnt

ReqDetail.ApprovedDate

ReqDetail.SelectionCode

ReqDetail.SelectionType

ReqHeader.ApprovedValue

ReqRoutedToUser.RequisitionType

ReqUser.RequisitionGroup

ReqUser.AdminUserFlag

ReqUser.AdminStopFlag

RmaDetail.PriceUom

RmaDetail.ConvFactRmaUm

RmaDetail.MulDivPrcFct

RmaDetail.LastActionDate

SalBranch.NextCreditDisc

SalBranch.NextDebitDisc

SalEcSales.SupplUnitQty

SalSalesTax.UkVatFlag

SorChanges.ReasonCode

SorDetail.SalesOrderDetStat

SorDetail.PreactorPriority

SorDetail.SalesOrderResStat

SorDetail.QtyReservedShip

SorLostSales.Version

SorLostSales.Release

SorLostSales.SalesOrder

SorLostSales.SalesOrderLine

SorMaster.DetailStatus

SorDetailRep.SalesOrderDetStat

SorMasterRep.DetailStatus

TblSoReason.IoLostSaleFlag

TpmJournal.GlIntUpdated

TpmJournal.GlIntPrinted

TpmJournal.GlIntYear

TpmJournal.GlIntPeriod

TpmJournal.GlJournal

TpmPriceDetail.PriceCode

TpmPromotion.PriceCode

TpmPromotion.PriceCodeCusPrc

TpmPromotionTrans.SPriceCode

TpmPromotionTrans.SPriceCodeCusPrc

WipJobClass.WipCtlGlCode

WipJobClass.WipInsGlCode

WipJobClass.WipAutoGlCode

WipJobClass.WipVarGlCode

WipCoProducts.QtyPerEnt

WipCoProducts.QtyToMakeEnt

WipCoProducts.QtyManufacturedEnt

WipCoProducts.TotalQtyScrapEnt

WipControl.LowUnpLabUpdYear

WipControl.LowUnpLabUpdPeriod

WipControl.LowUnpLabUpdJnl

WipControl.LowUnpBillUpdYear

WipControl.LowUnpBillUpdPrd

WipControl.LowUnpBillUpdJnl

WipControl.UnpLabUpdYear

WipControl.UnpLabUpdPeriod

WipControl.UnpBillUpdYear

WipControl.UnpBillUpdPeriod

WipInspect.QtyManufacturedEnt

WipInspect.QtyInspectedEnt

WipInspect.QtyAcceptedEnt

WipInspect.QtyScrappedEnt

WipInspect.QtyReworkedEnt

WipInspectDet.TrnQtyEnt

WipInspectSerial.QtyInspectedEnt

WipInspectSerial.QuantityEnt

WipInspectSerial.QtyAcceptedEnt

WipInspectSerial.QtyScrappedEnt

WipInspectSerial.QtyReworkedEnt

WipLabJnl.GlIntUpdated

WipLabJnl.GlIntPrinted

WipLabJnl.GlIntYear

WipLabJnl.GlIntPeriod

WipLabJnl.GlJournal

WipLabJnl.RunTimGlCode

WipLabJnl.SetTimGlCode

WipLabJnl.StartUpTimGlCode

WipLabJnl.TearDownTimGlCode

WipLabJnl.RunTimAnaEntry

WipLabJnl.SetTimGLCode

WipLabJnl.StartUpAnaEntry

WipLabJnl.TearDownAnaEntry

WipLabJnl.FixOverheadGlCode

WipLabJnl.VarOverheadGlCode

WipLabJnl.FixOverAnaEntry

WipLabJnl.VarOverAnaEntry

WipJobAllLab.IStartupQtyEnt

WipJobAllLab.IQuantityEnt

WipJobAllLab.IExpUnitRunTimEnt

WipJobAllLab.ITimeTakenEnt

WipJobAllLab.QtyScrappedEnt

WipJobAllLab.TransferQtyPctEnt

WipJobAllLab.ParentQtyPlanEnt

WipJobAllLab.OperYieldQtyEnt

WipJobAllLab.ParIssQtyEnt

WipJobAllLab.QtyCompletedEnt

WipJobAllLab.ResourceMask

WipJobAllLab.SchStartRunDate

WipJobAllLab.SchStartRunTime

WipJobAllLab.ScheduledMachine

WipJobAllLab.AllowOpSplit

WipSplitLabAll.ITimeTaken

WipSplitLabAll.IQuantity

WipSplitLabAll.MaxOpSpan

WipSplitLabAll.OpSlack

WipSplitLabAll.IStartupQtyEnt

WipSplitLabAll.IQuantityEnt

WipSplitLabAll.IExpUnitRunTimEnt

WipSplitLabAll.ITimeTakenEnt

WipSplitLabAll.QtyScrappedEnt

WipSplitLabAll.TransferQtyPctEnt

WipSplitLabAll.ParentQtyPlanEnt

WipSplitLabAll.OperYieldQtyEnt

WipSplitLabAll.ParIssQtyEnt

WipSplitLabAll.ResourceMask

WipSplitLabAll.SchStartRunDate

WipSplitLabAll.SchStartRunTime

WipSplitLabAll.ScheduledMachine

WipSplitLabAll.OperationStatus

WipSplitLabAll.OpSplitFlag

WipSplitLabAll.MaxOpDelay

WipJobAllMat.UnitQtyReqdEnt

WipJobAllMat.QtyIssuedEnt

WipJobAllMat.QtyBilledEnt

WipJobAllMat.ScrapQuantityEnt

WipJobAllMat.NetUnitQtyReqdEnt

WipJobAllMat.FixedQtyPerEnt

WipMaster.QtyToMakeEnt

WipMaster.QtyManufacturedEnt

WipMaster.TotQtyScrappedEnt

WipMaster.GrossQtyEnt

WipPartBook.QtySuppliedEnt

WipPartBook.GlIntUpdated

WipPartBook.GlIntPrinted

WipPartBook.GlIntYear

WipPartBook.GlIntPeriod

WipPartBook.GlJournal

WipDistrMat.GlIntUpdated

WipDistrMat.GlIntPrinted

WipDistrMat.GlIntYear

WipDistrMat.GlIntPeriod

WipDistrMat.GlJournal

WipJobPost.MQtyIssuedEnt

WipJobPost.MSerial

WipJobPost.MUnitCostActual

WipJobPost.LQtyScrappedEnt

WipJobPost.LQtyCompleteEnt

WipJobPost.LRunTimeHoursEnt

char(1)

char(15)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(1)

char(15)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

datetime

char(30)

char(50)

char(5)

decimal(14,2)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(6,0)

decimal(14,2)

char(3)

decimal(12,6)

char(1)

char(3)

decimal(12,6)

char(1)

char(3)

decimal(12,6)

char(1)

char(1)

char(15)

char(15)

char(15)

char(15)

char(15)

char(15)

char(15)

char(15)

char(15)

char(15)

decimal(7,0)

decimal(7,0)

decimal(7,0)

decimal(7,0)

decimal(7,0)

decimal(7,0)

decimal(7,0)

decimal(7,0)

decimal(7,0)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(14,2)

char(1)

char(3)

char(15)

char(15)

char(15)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(1)

decimal(7,0)

decimal(7,0)

decimal(7,0)

char(15)

decimal(7,0)

decimal(14,2)

char(15)

decimal(7,0)

decimal(14,2)

char(15)

decimal(7,0)

decimal(14,2)

char(15)

decimal(7,0)

decimal(14,2)

char(1)

char(2)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

decimal(3,0)

char(20)

char(20)

char(20)

char(20)

char(20)

char(20)

char(20)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(15)

char(15)

char(1)

char(15)

decimal(4,0)

decimal(14,2)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(1)

decimal(17,5)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(14,2)

decimal(4,0)

decimal(2,0)

decimal(4,0)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(6)

decimal(10,3)

decimal(12,6)

decimal(7,3)

decimal(10,3)

decimal(12,6)

decimal(7,3)

decimal(10,3)

decimal(12,6)

decimal(7,3)

decimal(10,3)

decimal(9,4)

decimal(9,4)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(10,3)

decimal(4,0)

decimal(4,0)

char(1)

char(7)

char(50)

char(50)

char(50)

decimal(14,2)

decimal(14,2)

decimal(4,0)

decimal(2,0)

decimal(4,0)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(10,3)

decimal(12,6)

decimal(7,3)

decimal(10,3)

decimal(12,6)

decimal(7,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(9,4)

decimal(9,4)

decimal(7,3)

decimal(10,3)

decimal(4,0)

decimal(4,0)

decimal(4,0)

char(1)

decimal(12,6)

decimal(7,3)

decimal(10,3)

char(15)

char(1)

char(1)

datetime

decimal(6,6)

char(2)

char(4)

datetime

decimal(5,0)

char(2)

char(4)

char(1)

char(40)

char(1)

char(20)

char(1)

datetime

char(15)

char(1)

char(1)

char(15)

char(1)

char(1)

char(1)

datetime

decimal(6,6)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(15)

decimal(7,0)

decimal(7,0)

char(4)

char(20)

char(3)

char(3)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(4,0)

decimal(2,0)

char(15)

decimal(10,3)

char(20)

char(3)

char(3)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(20)

char(20)

char(1)

char(20)

char(20)

char(20)

decimal(15,5)

char(6)

char(20)

char(3)

char(3)

char(1)

decimal(4,0)

char(1)

char(15)

char(2)

char(5)

char(3)

char(1)

datetime

decimal(8,0)

char(10)

datetime

decimal(8,0)

char(2)

char(2)

decimal(7,0)

decimal(12,3)

decimal(14,2)

decimal(14,2)

decimal(7,0)

decimal(12,3)

decimal(14,2)

decimal(14,2)

decimal(10,0)

char(30)

char(30)

char(30)

char(30)

char(30)

char(30)

decimal(3,0)

decimal(3,0)

decimal(5,2)

decimal(15,5)

char(6)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

char(15)

char(15)

char(15)

char(15)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(9,4)

decimal(9,4)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(10,3)

decimal(10,3)

char(6)

datetime

decimal(4,0)

char(6)

char(1)

decimal(12,6)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(12,6)

decimal(10,3)

char(1)

decimal(9,4)

decimal(9,4)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(10,3)

decimal(4,0)

decimal(4,0)

decimal(4,0)

char(1)

char(1)

decimal(2,0)

char(1)

decimal(7,3)

char(1)

decimal(12,6)

decimal(7,3)

decimal(10,3)

char(10)

datetime

char(30)

char(3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(4,0)

decimal(2,0)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(9,4)

decimal(9,4)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(10,3)

decimal(10,3)

char(6)

datetime

decimal(4,0)

char(6)

char(1)

decimal(12,6)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(12,6)

decimal(10,3)

char(1)

decimal(2,0)

char(1)

decimal(7,3)

char(1)

datetime

char(30)

char(3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

char(1)

decimal(12,6)

char(3)

char(3)

char(10)

char(10)

char(1)

decimal(9,4)

decimal(9,4)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(10,3)

decimal(4,0)

decimal(4,0)

decimal(4,0)

char(1)

char(1)

decimal(12,6)

decimal(7,3)

decimal(10,3)

datetime

char(30)

char(3)

decimal(14,2)

char(1)

char(6)

char(1)

char(1)

char(3)

decimal(10,6)

char(1)

datetime

decimal(6,0)

decimal(6,0)

decimal(12,6)

char(1)

char(6)

char(1)

decimal(2,0)

char(1)

decimal(7,3)

char(3)

char(3)

char(6)

decimal(4,0)

char(1)

char(1)

char(1)

char(1)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(2)

char(2)

char(2)

char(2)

char(2)

char(15)

char(15)

char(15)

char(15)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(4,0)

decimal(2,0)

decimal(4,0)

decimal(2,0)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(15)

char(15)

char(15)

char(15)

decimal(7,0)

decimal(7,0)

decimal(7,0)

decimal(7,0)

char(15)

char(15)

decimal(7,0)

decimal(7,0)

decimal(10,3)

decimal(10,3)

decimal(9,4)

decimal(9,4)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(10,3)

decimal(10,3)

char(6)

datetime

decimal(4,0)

char(6)

char(1)

decimal(9,4)

decimal(10,3)

decimal(4,0)

decimal(4,0)

decimal(10,3)

decimal(10,3)

decimal(9,4)

decimal(9,4)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(10,3)

char(6)

datetime

decimal(4,0)

char(6)

char(1)

char(1)

decimal(4,0)

decimal(12,6)

decimal(10,3)

decimal(10,3)

decimal(7,3)

decimal(12,6)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

decimal(10,3)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

char(1)

char(1)

decimal(4,0)

decimal(2,0)

decimal(5,0)

decimal(10,3)

char(20)

decimal(15,5)

decimal(10,3)

decimal(10,3)

decimal(7,2)

See also

What's new about SYSPRO 6.1


SYSPRO 6.0 Issue 010 SP2 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 010 SP1 and SYSPRO 6.0 Issue 010 SP2. It includes both SQL Server and C-ISAM changes.

Conversion process

There are relatively few database changes between issue 010 SP1 and issues 010 SP2.

The Data Migration Wizard will take you through the process of converting your issue 009, issue 010 or issue 010 SP1 format data files to issue 010 SP2. This conversion wizard converts both C-ISAM and SQL Server based companies.

Note that this conversion wizard can only be used to convert SYSPRO 6.0 issue 009, issue 010 or issue 010 SP1 format companies to issue 010 SP2. If the company is using a version of SYSPRO (or IMPACT Encore) on a prior version then you must install SYSPRO 6.0 issue 009 and migrate to that version first.

Steps to convert to issue 010 SP2

Install the SYSPRO 6.0 issue 010 SP2 software.

When you first log into each company the issue 010 SP2 conversion wizard will be invoked.

This wizard will handle the data file conversion for both SQL Server and C-ISAM based companies. There are various types of conversion required. The effect of each conversion is summarised below. A more detailed list of new tables, new columns and any other conversions is provided at the end of this topic.

Conversion type | SQL Server implications | C-ISAM implications
New table/file | Wizard adds table, column and key definitions | None - SYSPRO application programs create the new file when required
New column/field (using FILLER in C-ISAM file layout) | Wizard adds new column | None - SYSPRO application programs reference new field when required

Conversions

The following data conversions are performed when migrating from SP1 to SP2.

ADMTXH - This Tax History table will be generated from any ADMTXX sequential file previously created. This was only released during January 2008 to support multiple tax change histories.

CRMACT - The Contact Management Activity file has been reorganized for SP2 to cater for additional features.

CRMLAC - The Contact Management list of Account types is migrated from a sequential file to a SQL table/indexed file.

CRMLAT - The Contact Management list of Activity types is migrated from a sequential file to a SQL table/indexed file.

All other files/tables are new or have new fields/columns. None affect the length of any ISAM record or change a key in any way.

During the conversion process a log will be output to an ASCII text file in the work folder with the name ?IMPC6C.DAT - where ? is the company id. This can be useful to view a log of the process and to determine what occurred if the conversion fails for any reason.

Once the conversion has successfully completed the company control file (ADMCTL) will be updated to the new issue number so that you can log in as normal.

Note that when converting from issue 010 SP1 to issue 010 SP2 conversion there are only minor changes and therefore should be very fast.

Details of data conversions

The following details the database changes for issue 010 SP2.

Files That Are No Longer Required

The following files were planned to be used in previous releases but have never been used and will be removed during the conversion process. On SQL Server based systems these tables will be dropped during the conversion process.

Table name | ISAM file | Reason for deletion
CrmLanguage | CRMLNG | Defined in issue 010 SP1 - not used

Also note that after ADMTXX, CRMLAC and CRMLAT have been migrated from sequential files to ISAM files / SQL Server tables they will be physically deleted.

New Tables

The following files/tables are new for issue 010 SP2. On C-ISAM based systems these files will be created as and when necessary. On SQL Server based systems these tables will be created during the conversion process.

Table name | ISAM file | Description
AdmTaxHistory | ADMTXH | Admin Tax History
AdmUsaTaxHistory | ADMTXU | Admin US Advanced GeoTax/AVP Tax History
CrmAccountType | CRMLAC | Contact Account Types
CrmActivityType | CRMLAT | Contact Activity Types
PosDepositComments | POSDCM | Counter Sales Deposit Comments
SorQuoteListDetail | SORQLD | Sales Order Product List Detail
SorQuoteListType | SORQLT | Sales Order Product List Types

New C-ISAM Files

The following files are new for issue 010 SP2. All of these files always remain in C-ISAM, even on a SQL Server based system. They will be created as and when necessary. Note the Table name column indicates the name by which the C-ISAM file can be referenced in the Report Writer.

Table name | ISAM file | Description
WipLockNotes | WIPLKN | WIP Lock Job Notes

Columns added to existing tables

There are a number of new columns in existing tables for issue 010 SP2. The following lists the Table.ColumnName of each new column. You can use the Data Dictionary Viewer program (DDSBFI) to view more information about these column definitions.

LctCostingReg.ShippedQtyStkUm

ReqUser.UserForPorder

SorQuoteDet.ProductClass

SorRouteSoDetail.LineQuantity

TpmTrnWork.SelectedDispFlag

See also

What's new about SYSPRO 6.0 issue 010 SP2


SYSPRO 6.0 Issue 010 SP1 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 010 and SYSPRO 6.0 Issue 010 SP1. It includes both SQL Server and C-ISAM changes.

Conversion process

Due to the number of new and re-engineered modules for issue 010 SP1 there is a conversion wizard that takes you through the process of converting your issue 010 format data files to issue 010 SP1. This conversion wizard converts both C-ISAM and SQL Server based companies.

Note that this conversion wizard can only be used to convert SYSPRO issue 009 format companies to issue 010 SP1 or Issue 010 to Issue 010 SP1. If the company is using a version of SYSPRO (or IMPACT Encore) on a prior version then you must install SYSPRO 6.0 issue 009 and migrate to that version first.

Steps to convert to issue 010 SP1

Install the SYSPRO 6.0 issue 010 SP1 software.

When you first log into each company the issue 010 SP1 conversion wizard will be invoked.

This wizard will handle the data file conversion for both SQL Server and C-ISAM based companies. There are various types of conversion required. The effect of each conversion is summarised below. A more detailed list of new tables, new columns, renamed columns and new indexes is provided at the end of this topic.

Conversion type | SQL Server implications | C-ISAM implications
New table/file | Wizard adds table, column and key definitions | None - SYSPRO application programs create the new file when required
New column/field (using FILLER in C-ISAM file layout) | Wizard adds new column | None - SYSPRO application programs reference new field when required
New column/field (record length increased in C-ISAM file layout) | Wizard adds new column | Wizard requires a data file conversion to create the new format file
New index required | Wizard adds new index | Wizard requires to re-index file to add new index
SQL column renamed | Wizard renames column | None
Column/field changed in size | Wizard alters the column size | Wizard requires a data file conversion to reorganize the file layout making space for the larger column

The data conversions are required due to the large number of new features added to this version of SYSPRO.

Conversions

Note that when converting from SYSPRO 6.0 Issue 010 to Issue 010 SP1 there is only one file that is converted/changed in any way. This is the Inventory Quantity Discount table. The original table INVQTY (InvQtyDisc) is moved to a new table INVCQT (InvQtyDiscount) and the current code is added to the key. The original Inventory Quantity Discount table is removed when the wizard has completed.

All other files are new or have new fields/columns. None affect the length of any ISAM record or change a key in any way.

During the conversion process a log will be output to an ASCII text file in the work folder with the name ?IMPC6C.DAT - where ? is the company id. This can be useful to view a log of the process and to determine what occurred if the conversion fails for any reason.

Once the conversion has successfully completed the company control file (ADMCTL) will be updated to the new issue number so that you can log in as normal.

Note that the Issue 010 to Issue 010 SP1 ISAM conversion will be extremely fast as only the Quantity discount conversion is processed.

Details of data conversions

The following details the database changes for issue 010 SP1.

Files That Are No Longer Required

The following files were planned to be used in previous releases but have never been used and will be removed during the conversion process. On SQL Server based systems these tables will be dropped during the conversion process.

Table name | ISAM file | Reason for deletion
SorRouteSoHeader | SORRTH | Defined in issue 010 - not used

Also note that after INVQTY (InvQtyDisc) has been converted to INVCQT (InvQtyDiscount) it will also be removed from the database on a SQL Server environment and the file physically deleted on an ISAM environment.

New Tables

The following files are new for issue 010 SP1. On C-ISAM based systems these files will be created as and when necessary. On SQL Server based systems these tables will be created during the conversion process.

Table name | ISAM file | Description
ApCheckIss | APSCHK | A/P Checks Issued
ApDummyCheck | APSDCK | A/P Dummy Checks
ApPayRunDet | APSPRD | A/P Payment Run Detail
ApPayRunHdr | APSPRH | A/P Payment Run Header
ApTaxTransAmendJnl | APSTAJ | A/P Tax Transaction Amendment Journal
ApTaxTransDetail | APSTTD | A/P Tax Transaction Detail
ApTaxTransHeader | APSTTH | A/P Tax Transaction Header
ApTaxTrnsIntrastat | APSTTI | A/P Tax Transaction Intrastat Detail
ArDiscDrCrDetail | ARSDCE | A/R Discount Cr/Dr Notes Detail
BomResMaskDesc | BOMPRD | BOM Resource Mask Descriptions
BomResourceMask | BOMPRM | BOM Resource Mask
BomTools | BOMTOL | BOM Tools
BomToolSetTools | BOMTTO | BOM Tool Set Tools
CrmActivityAttend | CRMACA | Contact Activity Attendees
CrmActivityAttendU | CRMACB | Contact Activity Unknown Attendees
CrmAccount | CRMACC | Contact Accounts
CrmActivityAttach | CRMACH | Contact Activity Attachments
CrmActivity | CRMACT | Contact Activities
CrmAddress | CRMADD | Contact Address
CrmCategory | CRMCAT | Contact Category
CrmClass | CRMCLS | Contact Class
CrmContact | CRMCON | Contact Master
CrmControl | CRMCTL | Contact Control
CrmDate | CRMDAT | Contact Dates
CrmEmail | CRMEML | Contact Email Addresses
CrmLanguage | CRMLNG | Contact Language
CrmOrganization | CRMORG | Contact Organizations
CrmTelephone | CRMTEL | Contact Telephone Numbers
CrmTerritory | CRMTER | Contact Territory
CrmType | CRMTYP | Contact Type
CrmUrl | CRMURL | Contact URLs
InvQtyDiscount | INVCQT | Inventory Quantity Discount Breaks
IopColArchive | IOPCFA | IO Collection Archived Forecast
IopColLive | IOPCFL | IO Collection Live Forecast
IopConSalesAdjust | IOPCWA | IO Sales History Adjustments
IopConDraft | IOPCWD | IO Consolidated Warehouse Draft Forecast
IopColWarehouse | IOPCWH | IO Collection Warehouses
IopConSales | IOPCWS | IO Consolidated Warehouse Sales History
IopForeArchive | IOPFAR | IO Archived Forecasts
IopAmendmentJnl | IOPJNA | IO Collection Structure Amendment Jnl
QotParentInfo | QOTPAR | Quotation Estimate Parent Information
SorLoadSoHeader | SORRTO | Sales Order Load for Sales Order
SorLoadTransport | SORRTT | Sales Order Load Transport
WipSplitLabAll | WIPLSP | WIP Labor Allocation Splits

New C-ISAM Files

The following files are new for issue 010. All of these files always remain in C-ISAM, even on a SQL Server based system. They will be created as and when necessary. Note the Table name column indicates the name by which the C-ISAM file can be referenced in the Report Writer.

Table name | ISAM file | Description
WipDocumentFormat | WIPFMT | WIP Factory Documentation Format

New ASCII Sequential Files

The following files are new for issue 010. All of these files are ASCII text files, even on a SQL Server based system.

File | Description
ADMROL | Operator Roles
ADMSCR | Admin List of VB Snippets (IMPSCR.IMP)
ADMVBS | Admin List of VBS events (IMPVBS.IMP)

Columns added to existing tables

There are a large number of new columns in existing tables for issue 010. The following lists the Table.ColumnName of each new column. You can use the Data Dictionary Viewer program (DDSBFI) to view more information about these column definitions.

AdmSignatureLog.TransactionGuid

ApBank.Nationality

ApBranch.Nationality

ApControl.NextSupplier

ApPermEntries.Nationality

ApPermEntries.TaxRegnNum

ApInvoice.TaxReverse

ApInvoice.Tax2Reverse

ApInvoice.NationalitySource

ApInvoice.NationalityDest

ApInvoice.DiscountTaxCode

ArControl.NextCustomer

ArPermEntries.Nationality

ArPermEntries.TaxRegnNum

ArInvoice.TaxCode

ArMultAddress.Nationality

ArMultAddress.GeographicArea

ArMultAddress.TaxRegnNum

BomCoProducts.UomFlag

BomAmendmentJnl.OldUomFlag

BomAmendmentJnl.NewUomFlag

BomStructure.UomFlag

BomOperations.ResourceMask

BomOperations.MaxOpDelay

BomParentInfo.UomFlag

BomParentInfo.Narrations

BomWorkCentre.OpSplitFlag

CfgComponent.UomFlag

CshPermEntries.PostedFlagPrev1

CshPermEntries.PostedFlagPrev2

EccCoProducts.UomFlag

EccAmendmentJnl.OldUomFlag

EccAmendmentJnl.NewUomFlag

EccOperations.ResourceMask

EccParentInfo.UomFlag

EccStructure.UomFlag

GenCopyMaster.CurrentInd

GenMaster.CurrentInd

GenRuleMaster.SourceMovBal

GenRuleMaster.StatMovBal

GenSection.CurrentInd

InvMaster.ManufactureUom

InvMaster.ConvFactMuM

InvMaster.ManMulDiv

InvMaster.LookAheadWin

InvMaster.LoadingFactor

InvMaster.SupplUnitCode

InvWhControl.SiteId

InvWhControl.RollParentGl

InvWarehouse.ExcludeFromSched

IopColDraft.Freeze

IopColInstance.AggregationDate

IopColInstance.AggregationTime

IopColInstance.ConsolidateWh

IopColInstance.ListedWarehouse

IopColInstance.Decimals

IopSkuStructure.AbcClass

IopColSelect.AbcType

IopColSelect.AbcLevel

IopColSelect.AbcIncludeA

IopColSelect.AbcIncludeB

IopColSelect.AbcIncludeC

IopColSelect.AbcIncludeD

IopColSelect.AbcIncludeE

IopColSelect.AbcIncludeNoClass

IopColSelect.DateSaved

IopColSelect.TimeSaved

IopNewForecast.Freeze

IopWarehouse.AbcClass

IopWarehouse.AggregateCost

IopWarehouse.AggregatePrice

MdnDetailCons.PreactorPriority

MdnMasterCons.TpmEvaluatedFlag

MdnMasterCons.StandardComment

MdnDetail.PreactorPriority

MdnMaster.TpmEvaluatedFlag

MdnMaster.StandardComment

MdnDetailRepCon.PreactorPriority

MdnMasterRepCon.TpmEvaluatedFlag

MdnMasterRepCon.StandardComment

MrpCoProducts.Uom

MrpCoProducts.ConvFactUom

MrpCoProducts.ConvMulDiv

MrpJobAllLab.ITimeTaken

MrpJobAllLab.IQuantity

MrpJobAllLab.MaxOpSpan

MrpJobAllLab.OpSlack

MrpJobAllLab.SchStartDate

MrpJobAllLab.SchStartTime

MrpJobAllLab.SchEndDate

MrpJobAllLab.SchEndTime

MrpJobAllLab.OperationStatus

MrpJobAllLab.OpSplitFlag

MrpJobAllLab.MaxOpDelay

MrpQotSoDetail.QtyReserved

MrpQotSoDetail.PreactorPriority

MrpQotSoMasterHdr.TpmEvaluatedFlag

MrpQotSoMasterHdr.StandardComment

MdnDetailRep.PreactorPriority

MdnMasterRep.TpmEvaluatedFlag

MdnMasterRep.StandardComment

MrpJobMaster.UomFlag

MrpJobMaster.ConvFactUom

MrpJobMaster.ConvMulDiv

MrpJobMaster.ScheduleFlag

MrpJobMaster.SchStartDate

MrpJobMaster.SchStartTime

MrpJobMaster.SchEndDate

MrpJobMaster.SchEndTime

MrpJobAllMat.ConvFactUom

MrpJobAllMat.ConvMulDiv

MrpPoMasterDet.SelectionCode

MrpPoMasterDet.SelectionType

MrpQotDetail.ConfirmedFlag

MrpQotOperation.ResourceMask

MrpQotStructure.UomFlag

MrpSugCoProducts.Uom

MrpSugCoProducts.ConvFactUom

MrpSugCoProducts.ConvMulDiv

MrpSugJobMaster.UomFlag

MrpSugJobMaster.ConvFactUom

MrpSugJobMaster.ConvMulDiv

MrpSugJobMaster.ScheduleFlag

MrpSugJobMaster.SchStartDate

MrpSugJobMaster.SchStartTime

MrpSugJobMaster.SchEndDate

MrpSugJobMaster.SchEndTime

MrpSugJobAlLab.ITimeTaken

MrpSugJobAlLab.IQuantity

MrpSugJobAlLab.MaxOpSpan

MrpSugJobAlLab.OpSlack

MrpSugJobAlLab.SchStartDate

MrpSugJobAlLab.SchStartTime

MrpSugJobAlLab.SchEndDate

MrpSugJobAlLab.SchEndTime

MrpSugJobAlLab.OperationStatus

MrpSugJobAlLab.OpSplitFlag

MrpSugJobAlLab.MaxOpDelay

MrpSoDetail.QtyReserved

MrpSoDetail.PreactorPriority

MrpSoMasterHdr.TpmEvaluatedFlag

MrpSoMasterHdr.StandardComment

MrpSugJobAlMat.ConvFactUom

MrpSugJobAlMat.ConvMulDiv

MrpWarehouse.ExcludeFromSched

PorMasterDetail.SelectionCode

PorMasterDetail.SelectionType

PorEcReceipts.SupplUnitCode

QotDetail.ConfirmedFlag

QotOperation.ResourceMask

QotStructure.UomFlag

RmaDetail.SelectionCode

RmaDetail.SelectionType

RmaCrossShipment.SelectionCode

RmaCrossShipment.SelectionType

SalBranch.Nationality

SalEcSales.SupplUnitCode

SorControl.NextLoadNumber

SorDetailBin.QtyReserved

SorDetail.QtyReserved

SorDetail.PreactorPriority

SorDetailLot.QtyReserved

SorDetailSer.QtyReserved

SorMaster.TpmEvaluatedFlag

SorMaster.StandardComment

SorDeliveryPerf.OrderLineShipDate

SorDeliveryPerf.SalesOrderInitLine

SorQuoteDet.SelectionCode

SorQuoteDet.SelectionType

SorDetailBinRep.QtyReserved

SorDetailRep.PreactorPriority

SorDetailLotRep.QtyReserved

SorMasterRep.TpmEvaluatedFlag

SorMasterRep.StandardComment

SorDetailSerRep.QtyReserved

SorRouteDetail.LoadStatus

SorRouteDetail.LoadNumber

SorRouteDetail.Transport

SorRouteDetail.Employee

SorRouteMaster.Transport

WipCoProducts.Uom

WipCoProducts.ConvFactUom

WipCoProducts.ConvMulDiv

WipInspect.Uom

WipInspect.ConvFactUom

WipInspect.ConvMulDiv

MrpWipInspect.Uom

MrpWipInspect.ConvFactUom

MrpWipInspect.ConvMulDiv

WipJobAllLab.ITimeTaken

WipJobAllLab.IQuantity

WipJobAllLab.MaxOpSpan

WipJobAllLab.OpSlack

WipJobAllLab.SchStartDate

WipJobAllLab.SchStartTime

WipJobAllLab.SchEndDate

WipJobAllLab.SchEndTime

WipJobAllLab.OperationStatus

WipJobAllLab.OpSplitFlag

WipJobAllLab.MaxOpDelay

WipJobAllMat.ConvFactUom

WipJobAllMat.ConvMulDiv

WipMaster.UomFlag

WipMaster.ConvFactUom

WipMaster.ConvMulDiv

WipMaster.ScheduleFlag

WipMaster.SchStartDate

WipMaster.SchStartTime

WipMaster.SchEndDate

WipMaster.SchEndTime

WipJobPost.LTrnTime

WipJobPost.LTrnSplit

See also

What's new about SYSPRO 6.0 issue 010 SP1


SYSPRO 6.0 Issue 010 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 009 and SYSPRO 6.0 Issue 010. It includes both SQL Server and C-ISAM changes.

Conversion process

Due to the number of new and re-engineered modules for issue 010 there is a conversion wizard that takes you through the process of converting your issue 009 format data files to issue 010. This conversion wizard converts both C-ISAM and SQL Server based companies.

Note that this conversion wizard can only be used to convert SYSPRO issue 009 format companies to issue 010. If the company is using a version of SYSPRO (or IMPACT Encore) on a prior version then you must install SYSPRO 6.0 issue 009 and migrate to that version first.

Steps to convert to issue 010

Install the SYSPRO 6.0 issue 010 software.

When you first log into each company the issue 010 conversion wizard will be invoked.

This wizard will handle the data file conversion for both SQL Server and C-ISAM based companies. There are various types of conversion required. The effect of each conversion is summarised below. A more detailed list of new tables, new columns, renamed columns and new indexes is provided at the end of this topic.

Conversion type | SQL Server implications | C-ISAM implications
New table/file | Wizard adds table, column and key definitions | None - SYSPRO application programs create the new file when required
New column/field (using FILLER in C-ISAM file layout) | Wizard adds new column | None - SYSPRO application programs reference new field when required
New column/field (record length increased in C-ISAM file layout) | Wizard adds new column | Wizard requires a data file conversion to create the new format file
New index required | Wizard adds new index | Wizard requires to re-index file to add new index
SQL column renamed | Wizard renames column | None
Column/field changed in size | Wizard alters the column size | Wizard requires a data file conversion to reorganize the file layout making space for the larger column

The data conversions are required due to the large number of new features added to this version of SYSPRO. Part of the conversion process is dedicated to the following functions:

Converting TPM files

This is the first time that the Trade Promotions Module (TPM) has been incorporated into SYSPRO 6.0 as standard, however if you are using a prior version or the TPM system, the conversion wizard will take you through the process of migrating your old format files into the standard SYSPRO 6.0 system.

During the conversion process a log will be output to an ASCII text file in the work folder with the name ?IMPC6C.DAT - where ? is the company id. This can be useful to view a log of the process and to determine what occurred if the conversion fails for any reason.

Once the conversion has successfully completed the company control file (ADMCTL) will be updated to the new issue number so that you can log in as normal.

Details of data conversions

The following details the database changes for issue 010.

Tables requiring C-ISAM data file conversions

The following C-ISAM files require data file conversions due to an increase in their record length to cater for additional fields that cannot utilize the reserved FILLER area. In addition a few have changes to the primary and/or alternate keys. SQL Server based systems simply have the extra columns added without any other conversion required except for the change to indexes where appropriate.

Table name | ISAM file | Reason for change (includes Rlen/Klen)
AdmUsaTax | ADMTXG | 230/10 to 250/10 - largely reorganized
AssetEntries | ASSENT | 620/37 to 610/37 - 2 cost ctr fields increased
BomIcons | BOMICO | 50/11 to 55/11 - icons from 2 to 3
EccRevHistoryCost | ECCCST | 300/36 to 310/38 - wh in key
GenCopyControl | GENCCT | 570/1 to 600/1 - prd in saved key
GenCopyMaster | GENCMS | 260/16 to 360/16 - extra FILLER
GenControl | GENCTL | 570/1 to 600/1 - prd in saved key
GenJournalCtl | GENJNC | 220/9 to 230/11 - prd in key
GenJournalDetail | GENJND | 290/14 to 285/16 - prd in key GenJournalCtl
GenMaster | GENMST | 260/16 to 360/16 - extra FILLER
InvSerialTrn | INVSTD | 260/34 to 294/64 - stock code in key+chg idx
InvSerialHead | INVSTH | 240/22 to 280/52 - stock code in key+chg idx
InvWhatIfCost | INVWIF | 120/30 to 130/32 - wh in key
MdnMasterCons | MDNCMS | 1050/12 to 1080/12 - largely reorganized
MdnMasterRepCon | MDNPMS | 1050/12 to 1080/12 - largely reorganized
MrpQotStructure | MRPQST | 170/67 to 250/67 - 2 new fields
MdnMasterRep | MDNRMS | 1280/21 to 1310/21 - largely reorganized
MrpReqDetail | MRPREQ | 450/16 to 600/16 - extra space for future
MrpSugReqDetail | MRPSRQ | 450/16 to 600/16 - extra space for future
PosDrawer | POSDRW | 140/6 to 150/6 - larger hex string - ASCII->Hex
PrjContMaster | PRJCON | 350/20 to 550/20 - 16 new fields
QotStructure | QOTSTR | 170/67 to 250/67 - 2 new fields
RepLink | REPLNK | 300/36 to 410/38 - line no in key + 3 occurs
ReqDetail | REQDET | 450/16 to 600/16 - extra space for future

Files Requiring New Alternate Indexes

The following files have new alternate indexes. On C-ISAM based systems these will be re-indexed and on SQL Server based systems the new indexes will be added during the conversion process.

Table name | ISAM file | Description of New Index
AdmFormControl | ADMFRC | Form
AssetMaster | ASSMST | Capex
BomStructure | BOMMST | Offset
BsoReleaseIn | BSOINP | Confirmed flag
EccStructure | ECCSTR | Offset
InvFifoLifo | INVIFO | Receipt date
InvSerialTrn | INVSTD | Detail type
InvSerialTrn | INVSTD | Job
InvSerialHead | INVSTH | Date created
InvSerialHead | INVSTH | Serial number
LotTransactions | LOTTRN | Transaction type
MrpCapacityDyn | MRPDYN | Source of capacity
WipMaster | MRPJOB | Capex
MrpJobAllMat | MRPMAL | Operation offset
MrpPoMasterDet | MRPPOD | Asset capex number
MrpQotSoDetail | MRPQSD | Initial line
MrpReqDetail | MRPREQ | Asset capex code
WipMaster | MRPSJM | Capex
MrpSugJobAlMat | MRPSML | Operation offset
MrpSoDetail | MRPSOD | Initial line
MrpSugReqDetail | MRPSRQ | Asset capex code
MrpWipInspect | MRPWIN | Co-product line
PorMasterDetail | PORDET | Asset capex number
ReqDetail | REQDET | Asset capex code
SalProductClass | SALPRD | Product class
SorDetail | SORDET | Initial line
SorRouteDetail | SORRTD | Complete loads
WipCapacityDyn | WIPCAP | Source of capacity
WipInspect | WIPINC | Co-product line
WipJobAllMat | WIPMAL | Operation offset
WipMaster | WIPMST | Capex

Files Requiring Change to Existing Alternate Indexes

The following files have changes to existing alternate indexes. On C-ISAM based systems these will be re-indexed and on SQL Server based systems the indexes will be changed during the conversion process.

Table name | ISAM file | Description of Changed Index
MrpReqDetail | MRPREQ | Capex number
MrpSugReqDetail | MRPSRQ | Capex number
ReqDetail | REQDET | Capex number
SorRouteSoDetail | SORRTL | Sales order
SorRouteSoDetail | SORRTL | Route sequence

Files That Are No Longer Required

The following files were planned to be used in previous releases but have never been used and will be removed during the conversion process. On SQL Server based systems these tables will be dropped during the conversion process.

Table name | ISAM file | Reason for deletion
AdmActivityAudit | ADMAUD | Defined in issue 009 - not used
PrjContDeposit | PRJDEP | Defined in issue 009 - not used
PosPayIdx | POSXRF | Not used since Encore 4.0
PrjContRetention | PRJRET | Defined in issue 009 - not used

New Tables

The following files are new for issue 010. On C-ISAM based systems these files will be created as and when necessary. On SQL Server based systems these tables will be created during the conversion process.

Table name | ISAM file | Description
AdmFormList | ADMFRL | Admin Custom Form Validation List
AdmFormValidation | ADMFRV | Admin Custom Form Validation Lookup
AdmFormName | ADMFRF | Admin Custom Form - Form Name
AdmSignatureLogDet | ADMSID | Admin Electronic Signature Audit Detail
AdmSignatureLog | ADMSIG | Admin Electronic Signature Audit Log
ApArLink | APSARS | A/P Supplier to A/R Customer Linkage
ApIntegrationCtl | APSGLC | A/P Revaluation Integration Control
ApIntegrationDet | APSGLD | A/P Revaluation Integration Detail
ApInvoiceReval | APSREV | A/P Invoice Revaluations
ArDiscDrCrDet | ARSDCD | A/R Discount Cr/Dr Notes Details
ArDiscDrCrHdr | ARSDCH | A/R Discount Cr/Dr Notes Header
ArIntegrationCtl | ARSGLC | A/R Revaluation Integration Control
ArIntegrationDet | ARSGLD | A/R Revaluation Integration Detail
ArInvoiceReval | ARSREV | A/R Invoice Revaluations
AssetCapexAltCur | ASSCIA | Asset Capex Item Alternate Currency
AssetCapexSuspense | ASSCIS | Asset Capex Asset in Suspense
AssetCapexItem | ASSCIT | Asset Capex Item
AssetCapexClass | ASSCLS | Asset Capex Classification
AssetCapexLineAlt | ASSCRA | Asset Capex Requisition Line Alt Cur
AssetCapexLine | ASSCRL | Asset Capex Requisition Line
AssetCapexType | ASSCTP | Asset Capex Type
AssetCapexDefCtl | ASSDFC | Asset Capex Defaults Control
AssetCapexDefDet | ASSDFD | Asset Capex Defaults Detail
AssetCapexAmdJnl | ASSJNC | Asset Amendment Journal
BomCoPrdMatCost | BOMCDM | BOM Co-product Material Cost Percentages
BomCoPrdOpCost | BOMCDO | BOM Co-product Operation cost Percentages
BomCoProducts | BOMCOP | BOM Parent/Co-product Structure Master
BomParentInfo | BOMPAR | BOM Parent Information
EccCoPrdMatCost | ECCCDM | ECC Co-product Material Cost Percentages
EccCoPrdOpCost | ECCCDO | ECC Co-product Operation Cost Percentage
EccCoProducts | ECCCOP | ECC Parent/Co-product Structure Master
EccParentInfo | ECCPAR | ECC Parent Information
GenAnalysisCode | GENACD | G/L Analysis Category Codes
GenAnalysisCat | GENACT | G/L Analysis Categories
GenAnalysisCtl | GENADC | G/L Analysis Control
GenAnalysisTrn | GENADT | G/L Analysis Transactions
GenJournalCtlPrd | GENCJN | G/L Journal Number Control by Period
GenLastRevalRate | GENLRR | G/L Last Revaluation Rate
GenRuleDetail | GENRLD | G/L Rules Detail
GenRevalLog | GENRLG | G/L Revaluation Log
GenRuleMaster | GENRLH | G/L Rules Master
InvAppManufacturer | INVAMM | Inventory Approved Manufacturers
InvAppManfStock | INVAMS | Inventory Approved Manufacturer Stock
InvAppManfSupplier | INVAMV | Inventory Approved Manufacturer Supplier
InvSerialTrack | INVSTC | Inventory Serial Component Tracking
InvSerialCrossRef | INVSTR | Inventory Serial Cross Reference
IopColDraft | IOPCFR | IO Collection Draft Forecast
IopColInstance | IOPCIN | IO Collection Instance
IopCollection | IOPCOL | IO Collection Master
IopCollectAdjust | IOPCSA | IO Collection Sales History Adjustments
IopCollectSales | IOPCSH | IO Collection Sales History
IopSkuStructure | IOPCSK | IO Collection SKU Structures
IopColSelect | IOPCSL | IO Collection Selections
IopStructure | IOPCST | IO Collection Structure
LotCrossRef | LOTREF | Lot Traceability Cross Reference
LotTracking | LOTTRC | Lot Traceability Tracking
MrpCoPrdMatCost | MRPCDM | MRP Snapshot Job Co-product Mat App
MrpCoPrdOpCost | MRPCDO | MRP Snapshot Job Co-product Labor App
MrpCoProducts | MRPCOP | MRP Snapshot Job Co-products
MrpNotionalSch | MRPNOP | MRP Schedule for Notional Parts
MrpSugCoPrdMatCost | MRPSCM | MRP Suggested Job Co-product Mat App
MrpSugCoPrdOpCost | MRPSCO | MRP Suggested Job Co-product Labor App
MrpSugCoProducts | MRPSCP | MRP Suggested Job Co-products
MrpAllMatLot | MRPRAL | MRP Snapshot Booked Lots for Allocations
MrpAllMatSer | MRPRAS | MRP Snapshot Booked Serials for Allocs
PrjDepositDetail | PRJDPD | P&C Contract Deposit Detail
PrjDepositHeader | PRJDPH | P&C Contract Deposit Header
PrjRetentionDetail | PRJRTD | P&C Contract Retention Detail
PrjRetentionHeader | PRJRTH | P&C Contract Retention Header
PrjContBillSched | PRJSCH | P&C Contract Billing Schedules
ReqHeader | REQHDR | Requisition Header
SorReprintInv | SORRIN | Sales Order Invoice Reprint Cross-Ref
SorTriangCurRep | SORRTC | Sales Order Triangular Currency Reprint
TblSupplierClass | TBLAPC | A/P Supplier Classes
TblCurAmendmentJnl | TBLJNC | Admin Currency Amendment Journal
TpmAccrualTypes | TPMACT | TPM Accrual Types
TpmCredit | TPMCRD | TPM Master Sub-account index
TpmControl | TPMCTL | TPM Control
TpmCustomers | TPMCUS | TPM Customers
TpmDeductionCodes | TPMDED | TPM Deduction Codes
TpmDeductNotes | TPMDNO | TPM Deduction Notes
TpmDeductTran | TPMDTR | TPM Transactions for Deductions
TpmJournal | TPMJNL | TPM Journal
TpmProductGroup | TPMMPG | TPM Product Group Master
TpmDeductionMaster | TPMMST | TPM Deductions Review Master
TpmTransaction | TPMPDT | TPM Promotion Transactions
TpmPromThreshold | TPMPFG | TPM Free Goods Thresholds
TpmItemList | TPMPLS | TPM Promotion Item List
TpmPriceDetail | TPMPRD | TPM Pricing Detail
TpmPromotion | TPMPRO | TPM Promotion Master
TpmPromotionTrans | TPMPTR | TPM Promotion Transactions
TpmTrnWorkDetail | TPMPWD | TPM Promotion Work File Global Detail
TpmTrnWork | TPMPWK | TPM Promotion Work File
TpmResolution | TPMRES | TPM Resolution Codes
WipCoPrdMatCost | WIPCDM | WIP Co-product Mat Cost Apportionment
WipCoPrdOpCost | WIPCDO | WIP Co-product Labor Cost Apportionment
WipCoProducts | WIPCOP | WIP Job Co-products
WipAllMatLot | WIPRAL | WIP Booked Lots for Allocations
WipAllMatSer | WIPRAS | WIP Booked Serials for Allocations
WipReservedLots | WIPRJL | WIP Reserved Lots for Parent Part
WipReservedSerial | WIPRJS | WIP Reserved Serials for Job/Parent Part

New C-ISAM Files

The following files are new for issue 010. All of these files always remain in C-ISAM, even on a SQL Server based system. They will be created as and when necessary. Note the Table name column indicates the name by which the C-ISAM file can be referenced in the Report Writer.

Table name | ISAM file | Description
{none} | ADMBOS | Admin Business Object Status
AdmPrjPreferences | ADMPRJ | Projects and Contracts Preferences
AdmSignatureCon | ADMSCN | Admin Electronic Signature Condition
AdmSignatureCtl | ADMSCT | Admin Electronic Signature Control
AdmSignatureTrig | ADMSIT | Admin Electronic Signature Triggers
AdmSignatureVar | ADMSIV | Admin Electronic Signature Variables
AdmSignatureDetail | ADMSIX | Admin Electronic Signature Detail
{none} | ARSDFT | A/R Discount Cr/Dr Notes Format setup
{none} | ARSFMT | A/R Document Formats
DdsColumns | DDSCOL | Data Dictionary Columns
DdsForeignKeys | DDSFKY | Data Dictionary Foreign Key Linkages
DdsIndexes | DDSIDX | Data Dictionary Indexes
DdsTables | DDSTAB | Data Dictionary Tables

New ASCII Sequential Files

The following files are new for issue 010. All of these files are ASCII text files, even on a SQL Server based system.

File | Description
ADMFKY | Admin List of Foreign Keys (IMPFKY.IMP)
ADMQVW | Admin Quick View Fields (IMPQVW.IMP)
ADMSRS | Reporting Services Diagnostic Log

Columns added to existing tables

There are a large number of new columns in existing tables for issue 010. The following lists the Table.ColumnName of each new column. You can use the Data Dictionary Viewer program (DDSBFI) to view more information about these column definitions.

AdmFormControl.TableName

AdmFormControl.FormNumber

ApSupplierAddr.ShippingInstrs

ApBranch.PoPrefix

ApBranch.PoNextNumber

ApBranch.GrnPrefix

ApBranch.GrnNextNumber

ApChIssued.PaymentNumber

ApControl.NextPaymentNumber

ApControl.MtdRevaluations#

ApGlDisburse.AnalysisEntry

ApGlDisburse.PaymentNumber

ApGlExpAp.AnalysisEntry

ApPermEntries.AnalysisEntry

ApInvoice.PaymentNumber

ApInvoice.InvoiceTakeOn

ApInvoice.FixExchangeRate

ApInvoice.NextRevalNo

ApJnlDistrib.AnalysisEntry

ApJnlSummary.AnalysisEntry

ApInvoicePay.InvoiceTakeOn

ApInvoicePay.PaymentNumber

ArCustomerBal.TaxPortion

ArControl.DebitDiscReq

ArControl.NextCreditDisc

ArControl.NextDebitDisc

ArControl.PerCreditDisc

ArControl.PerDebitDisc

ArControl.MtdRevaluations#

ArInvoice.TaxStatus

ArInvoice.TaxPortion

ArInvoice.FixedRateFlag

ArInvoice.NextRevalNo

ArCshJnlDet.DrAnalysisEntry

ArCshJnlDet.AdjAnalysisEntry

ArSalesMove.SalesOrderLine

ArCustomer.TpmCustomerFlag

ArCustomer.SalesWarehouse

ArCustomer.TpmPricingFlag

ArCustomer.ArStatementNo

ArCustomer.TpmCreditCheck

ArCustomer.WholeOrderShipFlag

ArCustomer.MinimumOrderValue

ArCustomer.MinimumOrderChgCod

ArGlPayments.AnalysisEntry

ArGlSales.AnalysisEntry

ArTrnDetail.SalesOrderLine

AssetDistReg.AnalysisEntry

AssetDeprEnt.DepAnalysisEntry

AssetDeprEnt.AccDepAnalysisEnt

AssetMaster.CapexLine

BomAmendmentJnl.OldRollUpCostFlag

BomAmendmentJnl.OldWarehouse

BomAmendmentJnl.OldIgnoreFloorFlag

BomAmendmentJnl.NewRollUpCostFlag

BomAmendmentJnl.NewWarehouse

BomAmendmentJnl.NewIgnoreFloorFlag

BomStructure.RollUpCost

BomStructure.Warehouse

BomStructure.IgnoreFloorFlag

BomStructure.CoProductCostVal

BomOperations.CoProductCostVal

BomWorkCentre.ChargeCode

CfgComponent.RollUpCostFlag

CfgComponent.IgnoreFloorFlag

CshApPayments.PaymentNumber

CshPermEntries.AnalysisEntry

CshJnlGl.AnalysisEntry

CshTransactions.PaymentNumber

EccAmendmentJnl.OldRollUpCostFlag

EccAmendmentJnl.OldWarehouse

EccAmendmentJnl.OldIgnoreFloorFlag

EccAmendmentJnl.NewRollUpCostFlag

EccAmendmentJnl.NewWarehouse

EccAmendmentJnl.NewIgnoreFloorFlag

EccRevHistoryCost.Warehouse

EccOperations.TransferQtyOrPct

EccOperations.TransferQtyPct

EccOperations.CoProductCostVal

EccStructure.RollUpCostFlag

EccStructure.Warehouse

EccStructure.IgnoreFloorFlag

EccStructure.CoProductCostVal

EftNonExtractDet.PaymentNumber

EftVoidJnlDet.PaymentNumber

GenCopyCommitDet.CompleteFlag

GenCopyControl.UnpPer

GenCopyControl.AuthoriseJournals

GenCopyControl.LimitCapturerView

GenCopyControl.NextJnlNoPeriod

GenCopyControl.AnalyzeAssets

GenCopyControl.AnalyzeLiabilities

GenCopyControl.AnalyzeCapital

GenCopyControl.AnalyzeRevenue

GenCopyControl.AnalyzeExpense

GenCopyControl.AnalyzeStat

GenCopyControl.NextAnalysisNo

GenCopyMaster.AnalysisRequired

GenCopyMaster.AnalysisCategory

GenControl.UnpPer

GenControl.AuthoriseJournals

GenControl.LimitCapturerView

GenControl.NextJnlNoPeriod

GenControl.AnalyzeAssets

GenControl.AnalyzeLiabilities

GenControl.AnalyzeCapital

GenControl.AnalyzeRevenue

GenControl.AnalyzeExpense

GenControl.AnalyzeStat

GenControl.NextAnalysisNo

GenCopyTrans.AnalysisEntry

GenEntriesDetail.AnalysisEntry

GenJournalCtl.AuthorisedBy

GenJournalCtl.PostedBy

GenJournalCtl.Authorised

GenJournalDetail.GlPeriod

GenJournalDetail.AnalysisEntry

GenMaster.AnalysisRequired

GenMaster.AnalysisCategory

GenCommitDetail.CompleteFlag

GenRecJnlCtl.AuthorisedBy

GenRecJnlCtl.Authorised

GenTransaction.AnalysisEntry

GenSection.AnalysisRequired

GenSection.AnalysisCategory

InvControl.SerialPrefix

InvControl.SerialSuffix

InvDistribution.AnalysisEntry

InvJournalCtl.AnalysisEntry

InvJournalDet.AnalysisEntry

InvJournalDet.DrAnalysisEntry

InvJournalDet.PriceAnalysisEnt

InvMaster.SerialPrefix

InvMaster.SerialSuffix

InvMaster.ReturnableItem

InvMaster.ProductGroup

InvMaster.PriceType

InvMaster.Basis

InvMaster.ManualCostFlag

InvSerialTrn.StockCode

InvWhControl.WipControlGlCode

InvWhControl.WipVarCtlGlCode

InvWhControl.WipAutoVarGlCode

InvWarehouse.OrderPolicy

InvWarehouse.MajorOrderMult

InvWarehouse.MinorOrderMult

InvWarehouse.OrderMinimum

InvWarehouse.OrderMaximum

InvWarehouse.OrderFixPeriod

InvWarehouse.ManualCostFlag

InvWarehouse.LeadTime

InvWarehouse.ManufLeadTime

InvWarehouse.TransferCost

InvWarehouse.ImplosionNum

LctShipmentHdrA.PlaceOfShipment

LctShipmentHdrA.PlaceOfDestination

LctCostingReg.SupCatalogue

LctShipmentHdr.PlaceOfShipment

LctShipmentHdr.PlaceOfDestination

LotDetail.QtyReserved

MdnDetailCons.NDepRetFlagProj

MdnDetailCons.NRetentionJob

MdnDetailCons.NSrvMinQuantity

MdnDetailCons.NChargeCode

MdnDetailCons.TpmUsageFlag

MdnDetailCons.PromotionCode

MdnDetailCons.TpmSequence

MdnDetailCons.SalesOrderInitLine

MdnMasterCons.TpmPickupFlag

MdnDetail.NDepRetFlagProj

MdnDetail.NRetentionJob

MdnDetail.NSrvMinQuantity

MdnDetail.NChargeCode

MdnDetail.TpmUsageFlag

MdnDetail.PromotionCode

MdnDetail.TpmSequence

MdnDetail.SalesOrderInitLine

MdnMaster.TpmPickupFlag

MdnDetailRepCon.NDepRetFlagProj

MdnDetailRepCon.NRetentionJob

MdnDetailRepCon.NSrvMinQuantity

MdnDetailRepCon.NChargeCode

MdnDetailRepCon.TpmUsageFlag

MdnDetailRepCon.PromotionCode

MdnDetailRepCon.TpmSequence

MdnDetailRepCon.SalesOrderInitLine

MdnMasterRepCon.TpmPickupFlag

MdnMasterRep.TpmPickupFlag

MdnDetailRep.NDepRetFlagProj

MdnDetailRep.NRetentionJob

MdnDetailRep.NSrvMinQuantity

MdnDetailRep.NChargeCode

MdnDetailRep.TpmUsageFlag

MdnDetailRep.PromotionCode

MdnDetailRep.TpmSequence

MdnDetailRep.SalesOrderInitLine

MrpBuildSchedule.Route

MrpBuildSchedJnl.Route

MrpBuildSchedJnl.OldRoute

MrpJobMaster.ReservedLotSerFlag

MrpJobMaster.NotionalPart

MrpJobMaster.CoProductCostMet

MrpJobMaster.CoProductCostVal

MrpJobMaster.CoProductType

MrpJobMaster.CapexCode

MrpJobMaster.CapexLine

MrpJobAllLab.HoursBilled

MrpJobAllLab.CoProductCostVal

MrpLotDetail.QtyReserved

MrpJobAllMat.ReservedLotSerFlag

MrpJobAllMat.RollUpCostFlag

MrpJobAllMat.CoProductCostVal

MrpJobAllMat.ReservedLotQty

MrpJobAllMat.ReservedSerQty

MrpPoMasterDet.AssetFlag

MrpPoMasterDet.CapexNum

MrpPoMasterDet.CapexLine

MrpQotSoDetail.NDepRetFlagProj

MrpQotSoDetail.NRetentionJob

MrpQotSoDetail.NSrvMinQuantity

MrpQotSoDetail.NChargeCode

MrpQotSoDetail.TpmUsageFlag

MrpQotSoDetail.PromotionCode

MrpQotSoDetail.TpmSequence

MrpQotSoDetail.SalesOrderInitLine

MrpQotSoMasterHdr.TpmPickupFlag

MrpQotStructure.FixedQtyPerFlag

MrpQotStructure.FixedQtyPer

MrpReqDetail.AssetFlag

MrpReqDetail.CapexLine

MrpReqDetail.CapexCode

MrpReqDetail.RequisitionType

MrpReqDetail.IssueWarehouse

MrpSnapBuildSch.Route

MrpSugJobMaster.ReservedLotSerFlag

MrpSugJobMaster.NotionalPart

MrpSugJobMaster.CoProductCostMet

MrpSugJobMaster.CoProductCostVal

MrpSugJobMaster.CoProductType

MrpSugJobMaster.CapexCode

MrpSugJobMaster.CapexLine

MrpSugJobAlLab.HoursBilled

MrpSugJobAlLab.CoProductCostVal

MrpSugJobAlMat.ReservedLotSerFlag

MrpSugJobAlMat.RollUpCostFlag

MrpSugJobAlMat.CoProductCostVal

MrpSugJobAlMat.ReservedLotQty

MrpSugJobAlMat.ReservedSerQty

MrpSugReqDetail.AssetFlag

MrpSugReqDetail.CapexLine

MrpSugReqDetail.CapexCode

MrpSugReqDetail.RequisitionType

MrpSugReqDetail.IssueWarehouse

MrpSoDetail.NDepRetFlagProj

MrpSoDetail.NRetentionJob

MrpSoDetail.NSrvMinQuantity

MrpSoDetail.NChargeCode

MrpSoDetail.TpmUsageFlag

MrpSoDetail.PromotionCode

MrpSoDetail.TpmSequence

MrpSoDetail.SalesOrderInitLine

MrpSoMasterHdr.TpmPickupFlag

MrpWipInspect.CoProductLine

MrpWarehouse.OrderPolicy

MrpWarehouse.MajorOrderMult

MrpWarehouse.MinorOrderMult

MrpWarehouse.OrderMinimum

MrpWarehouse.OrderMaximum

MrpWarehouse.OrderFixPeriod

MrpWarehouse.ManualCostFlag

MrpWarehouse.LeadTime

MrpWarehouse.ManufLeadTime

MrpWarehouse.TransferCost

MrpWarehouse.ImplosionNum

PorMasterDetail.AssetFlag

PorMasterDetail.CapexNum

PorMasterDetail.CapexLine

PorHistReceipt.ExchangeRate

PorHistReceipt.MulDiv

PrjContMaster.DepositRequired

PrjContMaster.DepositMethod

PrjContMaster.DepositType

PrjContMaster.DepositPercent

PrjContMaster.DepositProdClass

PrjContMaster.DepositComment

PrjContMaster.DepositTaxCode

PrjContMaster.DepositGstTaxCode

PrjContMaster.RetentionRequired

PrjContMaster.RetentionMethod

PrjContMaster.RetentionType

PrjContMaster.RetentionProdClass

PrjContMaster.RetentionComment

PrjContMaster.RetentionTaxCode

PrjContMaster.RetentionGstTaxCod

PrjContMaster.TermsCode

QotSoMasterHdr.TpmPickupFlag

QotStructure.FixedQtyPerFlag

QotStructure.FixedQtyPer

ReqDetail.AssetFlag

ReqDetail.CapexLine

ReqDetail.CapexCode

ReqDetail.RequisitionType

ReqDetail.IssueWarehouse

ReqUser.CanAddReqn

ReqUser.CanAddReqnDetails

ReqUser.CanChgReqnDetails

ReqUser.CanApproveReqn

ReqUser.CanCreateOrder

ReqUser.MaxApproveValue

ReqUser.OnHoldFlag

ReqUser.ForwardToUser

RmaDetail.CreditReason

SalBranch.PrefixNextRma

SalBranch.NextRma

SorDetail.NDepRetFlagProj

SorDetail.NRetentionJob

SorDetail.NSrvMinQuantity

SorDetail.NChargeCode

SorDetail.TpmUsageFlag

SorDetail.PromotionCode

SorDetail.TpmSequence

SorDetail.SalesOrderInitLine

SorMaster.TpmPickupFlag

SorDetailRep.NDepRetFlagProj

SorDetailRep.NRetentionJob

SorDetailRep.NSrvMinQuantity

SorDetailRep.NChargeCode

SorDetailRep.TpmUsageFlag

SorDetailRep.PromotionCode

SorDetailRep.TpmSequence

SorDetailRep.SalesOrderInitLine

SorMasterRep.TpmPickupFlag

SorRouteDetail.LoadCompleteFlag

SorRouteSoDetail.DispatchNote

SorRouteSoDetail.DispatchNoteLine

SorServiceCharge.StockCodeReturn

SorServiceCharge.MinimumQuantity

TblSoShipInst.TpmPickupFlag

WipLabJnl.CoProductLine

WipJobAllLab.HoursBilled

WipJobAllLab.CoProductCostVal

WipJobAllMat.ReservedLotSerFlag

WipJobAllMat.RollUpCostFlag

WipJobAllMat.CoProductCostVal

WipJobAllMat.ReservedLotQty

WipJobAllMat.ReservedSerQty

WipMaster.ReservedLotSerFlag

WipMaster.NotionalPart

WipMaster.CoProductCostMet

WipMaster.CoProductCostVal

WipMaster.CoProductType

WipMaster.CapexCode

WipMaster.CapexLine

WipPartBook.CoProductLine

WipPartBook.CoProduct

WipDistrLab.CoProductLine

WipDistrLab.AnalysisEntry

WipDistrMat.CoProductLine

WipDistrMat.AnalysisEntry

WipInspect.CoProductLine

WipInspectSerial.CoProductLine

WipScrapDet.CoProductLine

See also

What's new about SYSPRO 6.0 issue 010


SYSPRO 6.0 Issue 009 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 008 and SYSPRO 6.0 Issue 009. It includes both SQL Server and C-ISAM changes.

Conversion process

Due to the number of new and re-engineered modules for issue 009 there is a conversion wizard that takes you through the process of converting your issue 008 format data files to issue 009. This conversion wizard converts both C-ISAM and SQL Server based companies.

Note that this conversion wizard can only be used to convert SYSPRO issue 008 format companies to issue 009. If the company is using a version of SYSPRO (or IMPACT Encore) on a prior version then you must install SYSPRO 6.0 issue 008 and migrate to that version first.

SQL Server conversion script - ISSUE009.SQL

Prior to issue 009, administrators of a SQL Server based systems had to manually run a script called ISSUE???.SQL where ??? was the new SYSPRO version. It is no longer necessary to run this script manually as it will be automatically run by the issue 009 conversion wizard. The ISSUE009.SQL script that is run automatically is stored in base\scripts.

Steps to convert to issue 009

Install the SYSPRO 6.0 issue 009 software.

When you first log into each company the issue 009 conversion wizard will be invoked.

This wizard will handle the data file conversion for both SQL Server and C-ISAM based companies. There are various types of conversion required. The effect of each conversion is summarised below. A more detailed list of new tables, new columns, renamed columns and new indexes is provided at the end of this topic.

Conversion type | SQL Server implications | C-ISAM implications
New table/file | Wizard adds table, column and key definitions | None - SYSPRO application programs create the new file when required
New column/field (using FILLER in C-ISAM file layout) | Wizard adds new column | None - SYSPRO application programs reference new field when required
New column/field (record length increased in C-ISAM file layout) | Wizard adds new column | Wizard requires a data file conversion to create the new format file
New index required | Wizard adds new index | Wizard requires to re-index file to add new index
SQL column renamed | Wizard renames column | None
Column/field changed in size | Wizard alters the column size | Wizard requires a data file conversion to reorganize the file layout making space for the larger column

The data conversions are required due to the large number of new features added to this version of SYSPRO. Part of the conversion process is dedicated to the following functions:

Converting Assets Register files

This conversion requires transactional data to have a period applied and to improve the General Ledger integration. You will be prompted during this conversion for information and to verify the Assets register period end dates

Converting RMA files

This is the first time that the Return Merchandise Authorization (RMA) system has been incorporated into SYSPRO 6.0 as standard, however if you are using a prior version or the RMA system, the conversion wizard will take you through the process of migrating your old format files into the standard SYSPRO 6.0 system.

During the conversion process a log will be output to the job logging system - including detail entries for each phase of the conversion process. In addition an ASCII text file with a log will be output the to work folder with the name IMPC6B.DAT.

Once the conversion has successfully completed the company control file (ADMCTL) will be updated to the new issue number so that you can log in as normal.

Details of data conversions

The following details the database changes for issue 009.

Assets Register Conversion

One of the major enhancements to issue 009 is that the Assets Register system has been largely re-engineered. This includes making the transactional data multi-period aware, in addition the General Ledger Integration has been vastly improved. These changes necessitate a number of changes to the Assets register file structures.

The following tables/files are saved during the conversion process. Note that the existing table/file names will have different formats after the conversion process. The old versions are stored for informational purposes only and are not used once the conversion has completed successfully.

Table name | ISAM file | Saved as table name | Saved as ISAM file name
AssetControl | ASSCTL | AssetControlOld | ASSCTO
AssetGroup | ASSGRP | AssetGroupOld | ASSGRO
AssetMaster | ASSMST | AssetMasterOld | ASSMSO

Tables with renamed column names

The following tables have had columns renamed to make them more meaningful. This has no effect on C-ISAM based systems.

Table name | ISAM file | Old column name | New column name
GrnMatching | GRNMAT | ApEntryNumber | SubEntryNumber
AssetGroup | ASSGRP | YtdRevenue | MinBookValue

Tables requiring C-ISAM data file conversions

The following C-ISAM files require data file conversions due to an increase in their record length to cater for additional fields that cannot utilize the reserved FILLER area. SQL Server based systems simply have the extra columns added without any other conversion required.

Table name | ISAM file | Reason for change
AssetAmendmentJnl | ASSJNA | File reorganized for Asset Register Conversion
AssetControl | ASSCTL | File reorganized for Asset Register Conversion
AssetDistReg | ASSDIS | File reorganized for Asset Register Conversion
AssetGroup | ASSGRP | File reorganized for Asset Register Conversion
AssetMaster | ASSMST | File reorganized for Asset Register Conversion
BomAmendmentJnl | BOMJNA | Record length changed (+12 new columns)
BomStructure | BOMMST | Record length changed (+2 new columns)
EccAmendmentJnl | ECCJNA | Record length changed (+12 new columns)
EccStructure | ECCSTR | Record length changed (+2 new columns)
MrpJobMaster | MRPJOB | Record length changed (+4 new columns)
MrpSugJobMaster | MRPSJM | Record length changed (+4 new columns)
PrjJobHierDet | PRJDET | Record length changed (+14 new columns)
PrjLibStdHier | PRJLIB | Record length changed (+10 new columns)
WipInspect | WIPINC | Record length changed 458 -> 480 (2 cols increased in size)
MrpWipInspect | MRPWIN | Record length changed 458 -> 480 (2 cols increased in size)
WipJobPost | WIPPST | Record length changed (+4 new columns)
WipLabJnl | WIPJNL | Record length changed (+2 new columns)
WipMaster | WIPMST | Record length changed (+4 new columns)

New Tables

Table name | ISAM file | Description
AdmActivityAudit | ADMAUD | Admin Activity Audit
AssetCostCenter | ASSCCE | Asset Cost Center
AssetCount | ASSCNT | Asset Count
AssetControl | ASSCTL | Asset Control (new issue 009 format)
AssetControlOld | ASSCTO | Asset Control (Issue 008 Format)
AssetDistHead | ASSDIH | Asset Distribution Header
AssetDeprEnt | ASSDPR | Asset Depreciation Calculation Details
AssetEntries | ASSENT | Asset Entries
AssetIntegCtl | ASSGLC | Asset Ledger Integration Control
AssetIntegDet | ASSGLD | Asset Ledger Integration Detail
AssetGroup | ASSGRP | Asset Group (new issue 009 format)
AssetGroupOld | ASSGRO | Asset Group (Issue 008 Format)
AssetHistory | ASSHST | Asset History
AssetLocation | ASSLOC | Asset Location
AssetMaster | ASSMST | Asset Master (new issue 009 format)
AssetMasterOld | ASSMSO | Asset Master (Issue 008 Format)
AssetOwner | ASSOWN | Asset Owner
AssetReasonDisp | ASSRED | Asset Reason for Disposal
AssetReasonReval | ASSRER | Asset Reason for Revaluation
AssetStatus | ASSSTA | Asset Status
AssetType | ASSTYP | Asset Type
EftExtractAudit | EFTAEX | EFT Batch Extract Audit
EftApSupplier | EFTAPS | EFT A/P Supplier Extra Details
EftBankCtl | EFTBNK | EFT Bank Control
EftBatchCtl | EFTBTC | EFT Batch Control
EftCshSupplier | EFTCBS | EFT Cash Book Supplier Master
EftCshTrans | EFTCSH | EFT Cashbook Transactions Not Yet Paid
EftControl | EFTCTL | EFT Control
EftCbAmendmentJnl | EFTJNA | EFT C/B Supplier Amendment Journal
EftNonExtractDet | EFTNPD | EFT Non Extracted Payments Detail
EftNonExtractHdr | EFTNPH | EFT Non Extracted Payments Header
EftExtractDet | EFTPDD | EFT Extracted Payments Detail
EftExtractHdr | EFTPDH | EFT Extracted Payments Header
EftVoidJnlDet | EFTVOD | EFT Voided Entries Detail Audit
EftVoidJnlHdr | EFTVOH | EFT Voided Entries Header Audit
GenSectionSecurity | GENACC | G/L Section Security
GenApportion | GENAPP | G/L Apportion Template
GenCopyAltCtl | GENCAC | Copy of G/L Alternate Currency Control
GenCopyAltDet | GENCAD | Copy of G/L Alternate Currency Detail
GenCopyAltHst | GENCAH | Copy of G/L Alternate Currency History
GenAnalysisSection | GENGLA | G/L Section Analysis
GenAnalysisBudget | GENGLB | G/L Budget Analysis
GenAnalysisCommit | GENGLU | G/L Commitment Analysis
GenSection | GENSEC | G/L Section
GenStructure | GENSTR | G/L Structure
IopParetoAnalysis | IOPABC | IO Stock code/Warehouse Pareto Analysis
IopSalesAdjust | IOPADJ | IO Sales History Adjustments
IopForeConsume | IOPCON | IO Forecast Consumption
IopForecast | IOPFOR | IO Forecast
IopCalendar | IOPFPR | IO Forecast Period Calendar
IopYearStart | IOPFPS | IO Forecast Year Start Dates
IopNewForecast | IOPNFR | IO New Forecast
IopProxies | IOPPRX | IO Forecasting Proxies
IopReportSet | IOPSET | IO Reporting Options
IopSalesReturns | IOPSLR | IO Sales History Returns
IopSales | IOPSLS | IO Sales History
IopTransactions | IOPTRN | IO History Transactions
IopWarehouse | IOPWHS | IO Stock code/Warehouse
MrpSnapIopConsume | MRPIOC | MRP Snapshot IO Forecast Consumption
MrpSnapIopForecast | MRPIOF | MRP Snapshot IO Forecast
PrjContDeposit | PRJDEP | P&C Contract Deposit
PrjOperatorNotice | PRJOPR | P&C Contract Operator Notifications
PrjContRetention | PRJRET | P&C Contract Retentions
PrjContBillSched | PRJSCH | P&C Contract Billing Schedule
RmaActionHistory | RMAAHS | RMA Action History
RmaComment | RMACMT | RMA Detail Line Comment
RmaDetailBin | RMADBI | RMA Detail Line Bins
RmaDetail | RMADET | RMA Detail
RmaDetailLot | RMADLO | RMA Detail Line Lots
RmaDetailSer | RMADSE | RMA Detail Line Serials
RmaMaster | RMAMST | RMA Master
RmaProblemCodes | RMAPRB | RMA Problem Codes
RmaRestockComp | RMARRC | RMA Restocking Components Temporary File
RmaCrossShipment | RMAXSH | RMA Cross Shipment Details

Columns added to existing tables

In C-ISAM all the fields reside in previous FILLER fields.

Table name | Column | Data type | ISAM file | ISAM field
AdmEvent | ComEventFlag | char(1) | ADMEVE | ADMEVE-COM-FLG
AdmEvent | MessageText | char(40) | ADMEVE | ADMEVE-MSG-TXT
AdmEvent | Operator | char(6) | ADMEVE | ADMEVE-MSG-OPER
AdmEvent | ProgramToRun | char(6) | ADMEVE | ADMEVE-MSG-PROG
AdmEvent | UseDate | decimal(1,0) | ADMEVE | ADMEVE-MSG-USE-DATE
AdmEvent | PreventDuplicate | decimal(1,0) | ADMEVE | ADMEVE-MSG-PREVENT
ApBank | NextEftNum | decimal(6,0) | APSBNK | APSBNK-EFT-NCK
ApListChHdr | ApPostMethod | char(1) | APSCHH | APSCHH-AP-POST
ApListChHdr | EftVoid | char(1) | APSCHH | APSCHH-EFT-VOID
ArInvoice | RetentionInv | char(1) | ARSINV | ARSINV-RET-INV
ArCustomer | FaxQuotes | char(1) | ARSMST | ARSMST-FAX-QUOTES
ArCustomer | RouteDistance | decimal(4,0) | ARSMST | ARSMST-ROUTE-SEQ
ArMultAddress | RouteCode | char(10) | ARSSHP | ARSSHP-ROUTE
ArMultAddress | RouteDistance | decimal(4,0) | ARSSHP | ARSSHP-ROUTE-SEQ
ArTrnDetail | EecInvoiceFlag | char(1) | ARSSTD | ARSSTD-EEC-INV
ArTrnDetail | Nationality | char(3) | ARSSTD | ARSSTD-EEC-NAT
ArTrnSummary | EecInvoiceFlag | char(1) | ARSSTS | ARSSTS-EEC-INV
ArTrnSummary | Nationality | char(3) | ARSSTS | ARSSTS-EEC-NAT
ArTrnTax | EecInvoiceFlag | char(1) | ARSSTX | ARSSTX-EEC-INV
ArTrnTax | Nationality | char(3) | ARSSTX | ARSSTX-EEC-NAT
AssetDepreciation | NumberOfPeriods | decimal(4,0) | ASSDEP | ASSDEP-PERS
AssetDepreciation | HalfRule | char(1) | ASSDEP | ASSDEP-HALF
AssetDistReg | AssetKey | char(15) | ASSDIS | ASSDIS-ASSENT-COD
AssetDistReg | EntryYear | decimal(4,0) | ASSDIS | ASSDIS-ASSENT-YEAR
AssetDistReg | EntryMonth | decimal(2,0) | ASSDIS | ASSDIS-ASSENT-MONTH
AssetDistReg | SystemDate | datetime | ASSDIS | ASSDIS-ASSENT-DATE
AssetDistReg | SystemTime | decimal(8,0) | ASSDIS | ASSDIS-ASSENT-TIME
AssetAmendmentJnl | AssetFileName | char(6) | ASSJNA | ASSJNA-FILE-NAME
BomAmendmentJnl | OldWetWeightPerc | decimal(4,2) | BOMJNA | BOMJNA-O-WET-PCT
BomAmendmentJnl | OldIncludeBatch | char(1) | BOMJNA | BOMJNA-O-INC-BATCH
BomAmendmentJnl | OldIncludeFromJob | char(8) | BOMJNA | BOMJNA-O-FROM-JOB
BomAmendmentJnl | OldIncludeToJob | char(8) | BOMJNA | BOMJNA-O-TO-JOB
BomAmendmentJnl | OldFixedQtyPerFlag | char(1) | BOMJNA | BOMJNA-O-FIXPER
BomAmendmentJnl | OldFixedQtyPer | decimal(10,3) | BOMJNA | BOMJNA-O-PAR-QTY
BomAmendmentJnl | NewWetWeightPerc | decimal(4,2) | BOMJNA | BOMJNA-N-WET-PCT
BomAmendmentJnl | NewIncludeBatch | char(1) | BOMJNA | BOMJNA-N-INC-BATCH
BomAmendmentJnl | NewIncludeFromJob | char(8) | BOMJNA | BOMJNA-N-FROM-JOB
BomAmendmentJnl | NewIncludeToJob | char(8) | BOMJNA | BOMJNA-N-TO-JOB
BomAmendmentJnl | NewFixedQtyPerFlag | char(1) | BOMJNA | BOMJNA-N-FIXPER
BomAmendmentJnl | NewFixedQtyPer | decimal(10,3) | BOMJNA | BOMJNA-N-PAR-QTY
BomStructure | FixedQtyPerFlag | char(1) | BOMMST | BOMSTR-FIXPER
BomStructure | FixedQtyPer | decimal(10,3) | BOMMST | BOMSTR-PAR-QTY
CshApPayments | EftBatch | char(6) | CSHAPD | CSHAPD-EFT-BATCH
CshTransactions | EftIndicator | char(1) | CSHTRD | CSHTRD-EFT
CshTransactions | Supplier | char(7) | CSHTRD | CSHTRD-SUP
CshTransactions | EftBatch | char(6) | CSHTRD | CSHTRD-EFT-BATCH
CshTransactions | ReconciledDate | datetime | CSHTRD | CSHTRD-REC-DAT
EccAmendmentJnl | OldWetWeightPerc | decimal(4,2) | ECCJNA | ECCJNA-O-WET-PCT
EccAmendmentJnl | OldIncludeBatch | char(1) | ECCJNA | ECCJNA-O-INC-BATCH
EccAmendmentJnl | OldIncludeFromJob | char(8) | ECCJNA | ECCJNA-O-FROM-JOB
EccAmendmentJnl | OldIncludeToJob | char(8) | ECCJNA | ECCJNA-O-TO-JOB
EccAmendmentJnl | OldFixedQtyPerFlag | char(1) | ECCJNA | ECCJNA-O-FIXPER
EccAmendmentJnl | OldFixedQtyPer | decimal(10,3) | ECCJNA | ECCJNA-O-PAR-QTY
EccAmendmentJnl | NewWetWeightPerc | decimal(4,2) | ECCJNA | ECCJNA-N-WET-PCT
EccAmendmentJnl | NewIncludeBatch | char(1) | ECCJNA | ECCJNA-N-INC-BATCH
EccAmendmentJnl | NewIncludeFromJob | char(8) | ECCJNA | ECCJNA-N-FROM-JOB
EccAmendmentJnl | NewIncludeToJob | char(8) | ECCJNA | ECCJNA-N-TO-JOB
EccAmendmentJnl | NewFixedQtyPerFlag | char(1) | ECCJNA | ECCJNA-N-FIXPER
EccAmendmentJnl | NewFixedQtyPer | decimal(10,3) | ECCJNA | ECCJNA-N-PAR-QTY
EccStructure | FixedQtyPerFlag | char(1) | ECCSTR | BOMSTR-FIXPER
EccStructure | FixedQtyPer | decimal(10,3) | ECCSTR | BOMSTR-PAR-QTY
GenCopyMaster | BusinessProcess1 thru BusinessProcess10 | char(3) | GENCMS | GENCMS-PROC-TYPE(x)
GenMaster | BusinessProcess1 thru BusinessProcess10 | char(3) | GENMST | GENMST-PROC-TYPE(x)
InvInspectSerial | ExpiryDate | datetime | INVINS | INVINS-EXP
InvMaster | InspectionFlag | char(1) | INVMST | INVMST-INSPECT
InvWhControl | SoDefaultDoc | char(1) | INVWHC | INVWHC-SCT-FORM
InvWhControl | RouteCode | char(10) | INVWHC | INVWHC-ROUTE
InvWhControl | RouteDistance | decimal(4,0) | INVWHC | INVWHC-ROUT-SEQ
InvWarehouse | RmaQtyIssued | decimal(10,3) | INVWHS | INVWHS-RMAQ-ISS
InvWarehouse | LastExtendedCost | decimal(15,5) | INVWHS | INVWHS-LAST-EXTCST
LotDetail | QtyAwaitingCredit | decimal(10,3) | LOTDET | LOTDET-QCRD
MdnMaster | IbtFlag | char(1) | MDNMST | MDNMST-IBT
MdnMaster | DateLastInvPrt | datetime | MDNMST | MDNMST-PRINV-DATE
MdnMasterRep | IbtFlag | char(1) | MDNRMS | MDNRMS-IBT
MdnMasterRep | DateLastInvPrt | datetime | MDNRMS | MDNRMS-PRINV-DATE
MrpReqDetail | Operator | char(6) | MRPREQ | MRPDET-ORIG-OPER
MrpReqDetail | CurrentOperator | char(6) | MRPREQ | MRPDET-HOLD-OPER
MrpJobMaster | GrossFlag | char(1) | MRPJOB | MRPJOB-GROSS
MrpJobMaster | GrossQty | decimal(10,3) | MRPJOB | MRPJOB-GROSS-QTY
MrpJobMaster | ExpLabCurrent | decimal(15,5) | MRPJOB | MRPJOB-STL-CUR
MrpJobMaster | ExpMatCurrent | decimal(15,5) | MRPJOB | MRPJOB-STM-CUR
MrpJobAllLab | ParentQtyPlanned | decimal(10,3) | MRPLAL | MRPLAL-PAR-QTY
MrpJobAllLab | OperYieldPct | decimal(4.2) | MRPLAL | MRPLAL-SCRAP
MrpJobAllLab | OperYieldQty | decimal(7,3) | MRPLAL | MRPLAL-SCRAP-QTY
MrpJobAllLab | ParIssQty | decimal(10,3) | MRPLAL | MRPLAL-ISS-QTY
MrpLotDetail | QtyAwaitingCredit | decimal(10,3) | MRPLOT | MRPLOT-QCRD
MrpSugJobAlLab | ParentQtyPlanned | decimal(10,3) | MRPSLL | MRPSLL-PAR-QTY
MrpSugJobAlLab | OperYieldPct | decimal(4.2) | MRPSLL | MRPSLL-SCRAP
MrpSugJobAlLab | OperYieldQty | decimal(7,3) | MRPSLL | MRPSLL-SCRAP-QTY
MrpSugJobAlLab | ParIssQty | decimal(10,3) | MRPSLL | MRPSLL-ISS-QTY
MrpJobAllMat | FixedQtyPerFlag | char(1) | MRPMAL | MRPMAL-FIXPER
MrpJobAllMat | FixedQtyPer | decimal(10,3) | MRPMAL | MRPMAL-PAR-QTY
MrpJobAllMat | NetUnitQtyReqd | decimal(12,6) | MRPMAL | MRPMAL-NET-REQ
MrpQotMaster | Fax | char(20) | MRPQMS | MRPQMS-FAX
MrpQotMaster | Telephone | char(20) | MRPQMS | MRPQMS-PHONE
MrpSugWipCtl | NextInspDoc | decimal(9,0) | MRPSJC | WIPCTL-INS-DOC
MrpSugWipCtl | NextScrDoc | decimal(9,0) | MRPSJC | WIPCTL-SCR-DOC
MrpSugJobMaster | GrossFlag | char(1) | MRPSJM | MRPSJM-GROSS
MrpSugJobMaster | GrossQty | decimal(10,3) | MRPSJM | MRPSJM-GROSS-QTY
MrpSugJobMaster | ExpLabCurrent | decimal(15,5) | MRPSJM | MRPSJM-STL-CUR
MrpSugJobMaster | ExpMatCurrent | decimal(15,5) | MRPSJM | MRPSJM-STM-CUR
MrpSugJobAlMat | FixedQtyPerFlag | char(1) | MRPSML | MRPSML-FIXPER
MrpSugJobAlMat | FixedQtyPer | decimal(10,3) | MRPSML | MRPSML-PAR-QTY
MrpSugJobAlMat | NetUnitQtyReqd | decimal(12,6) | MRPSML | MRPSML-NET-REQ
MrpSugReqDetail | Operator | char(6) | MRPSRQ | MRPSRQ-ORIG-OPER
MrpSugReqDetail | CurrentOperator | char(6) | MRPSRQ | MRPSRQ-HOLD-OPER
MrpWarehouse | RmaQtyIssued | decimal(10,3) | MRPWHS | MRPWHS-RMAQ-ISS
MrpWarehouse | LastExtendedCost | decimal(15,5) | MRPWHS | MRPWHS-LAST-EXTCST
PrjContMaster | HierarchyCode | char(8) | PRJCON | PRJCON-LIB-CODE
PrjContMaster | Customer | char(7) | PRJCON | PRJCON-CUS
PrjContMaster | RetentionCustomer | char(7) | PRJCON | PRJCON-RET-CUS
PrjContMaster | RetentionPrd | decimal(3,0) | PRJCON | PRJCON-RET-PRD
PrjContMaster | RetentionPct | decimal(5,2) | PRJCON | PRJCON-RET-PCT
PrjContMaster | FollowUpPrd | decimal(3,0) | PRJCON | PRJCON-FUP-PRD
PrjContMaster | PrgBillingMethod | char(1) | PRJCON | PRJCON-BIL-MET
PrjContMaster | BillDayOfMonth | decimal(2,0) | PRJCON | PRJCON-BIL-DAY
PrjContMaster | NumberOfBillings | decimal(3,0) | PRJCON | PRJCON-BIL-NO
PrjContMaster | BillingPercent | decimal(5,2) | PRJCON | PRJCON-BIL-PCT
PrjContMaster | NotationalBillVal | decimal(14,2) | PRJCON | PRJCON-BIL-NVAL
PrjJobHierDet | AnticipatedVal3 | decimal(14,2) | PRJDET | PRJDET-ANT-VAL3
PrjJobHierDet | CurrentExpMat | decimal(14,2) | PRJDET | PRJDET-CUR-MAT
PrjJobHierDet | CurrentExpLab | decimal(14,2) | PRJDET | PRJDET-CUR-LAB
PrjJobHierDet | CurrentExpSubct | decimal(14,2) | PRJDET | PRJDET-CUR-SUB
PrjJobHierDet | WipCtlGlCode | char(15) | PRJDET | PRJDET-WIP-LDG
PrjJobHierDet | TrackCostsOnly | char(1) | PRJDET | PRJDET-TRK-COST
PrjJobHierDet | WipCostTrkGlCode | char(15) | PRJDET | PRJDET-TRK-LDG
PrjJobHierDet | AllowStkTran | char(1) | PRJDET | PRJDET-ALLOW-STK
PrjJobHierDet | AllowNonTran | char(1) | PRJDET | PRJDET-ALLOW-NON
PrjJobHierDet | AllowLabTran | char(1) | PRJDET | PRJDET-ALLOW-LAB
PrjJobHierDet | AllowSubTran | char(1) | PRJDET | PRJDET-ALLOW-SUB
PrjJobHierDet | AllowSlsTran | char(1) | PRJDET | PRJDET-ALLOW-SLS
PrjJobHierDet | AllowPorTran | char(1) | PRJDET | PRJDET-ALLOW-POR
PrjJobHierDet | PctLimit | decimal(5,2) | PRJDET | PRJDET-PCT-LIMIT
PrjLibStdHier | WipCtlGlCode | char(15) | PRJLIB | PRJLIB-WIP-LDG
PrjLibStdHier | TrackCostsOnly | char(1) | PRJLIB | PRJLIB-TRK-COST
PrjLibStdHier | WipCostTrkGlCode | char(15) | PRJLIB | PRJLIB-TRK-LDG
PrjLibStdHier | AllowStkTran | char(1) | PRJLIB | PRJLIB-ALLOW-STK
PrjLibStdHier | AllowNonTran | char(1) | PRJLIB | PRJLIB-ALLOW-NON
PrjLibStdHier | AllowLabTran | char(1) | PRJLIB | PRJLIB-ALLOW-LAB
PrjLibStdHier | AllowSubTran | char(1) | PRJLIB | PRJLIB-ALLOW-SUB
PrjLibStdHier | AllowSlsTran | char(1) | PRJLIB | PRJLIB-ALLOW-SLS
PrjLibStdHier | AllowPorTran | char(1) | PRJLIB | PRJLIB-ALLOW-POR
PrjLibStdHier | PctLimit | decimal(5,2) | PRJLIB | PRJLIB-PCT-LIMIT
QotMaster | Fax | char(20) | QOTMST | QOTMST-FAX
QotMaster | Telephone | char(20) | QOTMST | QOTMST-PHONE
ReqDetail | Operator | char(6) | REQDET | REQDET-ORIG-OPER
ReqDetail | CurrentOperator | char(6) | REQDET | REQDET-HOLD-OPER
ReqRouting | Operator | char(6) | REQROU | REQROU-OPER-TO
ReqRouting | RoutingUser | char(3) | REQROU | REQROU-USER-FROM
ReqRouting | RoutingOperator | char(6) | REQROU | REQROU-OPER-FROM
ReqUser | InclPlanning | char(1) | REQUSR | REQUSR-INC-PLAN
SalSalesTax | EecInvoiceFlag | char(1) | SALTAX | SALTAX-EEC-INV
SalSalesTax | Nationality | char(3) | SALTAX | SALTAX-EEC-NAT
SalSalesTax | TaxRetSubmitted | char(1) | SALTAX | SALTAX-RET-SUB
SalSalesTax | YearRetSubmitted | decimal(4,0) | SALTAX | SALTAX-SUB-YEAR
SalSalesTax | MthRetSubmitted | decimal(2,0) | SALTAX | SALTAX-SUB-MONTH
SorRouteSoDetail | RouteDistance | decimal(4,0) | SORRTL | SORRTL-ROUTE-SEQ
WipControl | NextInspDoc | decimal(9,0) | WIPCTL | WIPCTL-INS-DOC
WipControl | NextScrDoc | decimal(9,0) | WIPCTL | WIPCTL-SCR-DOC
WipInspectDet | AltWarehouse | char(2) | WIPIND | WIPIND-ALT-WH
WipLabJnl | Reference | char(9) | WIPJNL | WIPJNL-L-REF
WipLabJnl | AddReference | char(30) | WIPJNL | WIPJNL-L-ADDREF
WipJobAllLab | ParentQtyPlanned | decimal(10,3) | WIPLAL | WIPLAL-PAR-QTY
WipJobAllLab | OperYieldPct | decimal(4.2) | WIPLAL | WIPLAL-SCRAP
WipJobAllLab | OperYieldQty | decimal(7,3) | WIPLAL | WIPLAL-SCRAP-QTY
WipJobAllLab | ParIssQty | decimal(10,3) | WIPLAL | WIPLAL-ISS-QTY
WipJobAllMat | FixedQtyPerFlag | char(1) | WIPMAL | WIPMAL-FIXPER
WipJobAllMat | FixedQtyPer | decimal(10,3) | WIPMAL | WIPMAL-PAR-QTY
WipJobAllMat | NetUnitQtyReqd | decimal(12,6) | WIPMAL | WIPMAL-NET-REQ
WipMaster | GrossFlag | char(1) | WIPMST | WIPMST-GROSS
WipMaster | GrossQty | decimal(10,3) | WIPMST | WIPMST-GROSS-QTY
WipMaster | ExpLabCurrent | decimal(15,5) | WIPMST | WIPMST-STL-CUR
WipMaster | ExpMatCurrent | decimal(15,5) | WIPMST | WIPMST-STM-CUR
WipJobPost | LScrapCode | char(2) | WIPPST | WIPPST-L-SCRAP
WipJobPost | LNonProdCode | char(2) | WIPPST | WIPPST-L-NPROD
WipJobPost | LReference | char(9) | WIPPST | WIPPST-L-REF
WipJobPost | LAddReference | char(30) | WIPPST | WIPPST-L-ADDREF

See also

What's new about SYSPRO 6.0 issue 009, SYSPRO 6.0 issue 008 database changes, SYSPRO 6.0 issue 007 database changes, SYSPRO 6.0 issue 006 database changes, Fields changed since Encore 4.0


SYSPRO 6.0 Issue 008 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 007 and SYSPRO 6.0 Issue 008. It includes both SQL Server and C-ISAM changes.

Conversion process

Install the SYSPRO 6.0 issue 008 software.

On a SQL Server based system you must run ISSUE008.SQL against each company database using Query Analyzer. Note that this adds a new AdmVersion table containing information about the current SYSPRO database version. This includes a log of when the ISSUE008.SQL script was run.

Conversion program

When you first log into each company the issue 008 conversion wizard will be invoked.

On a C-ISAM based system this converts the following files to issue 008 format. This includes increasing the tax tables from 8 occurrences to 26.

ISAM file | Table name | Description
APSD2C | ApTax2DistSum | A/P Supplier Second Tax Distribution Ctl
APSD2D | ApTax2DistDet | A/P Supplier Second Tax Distribution Det
APSTDD | ApTaxDistDet | A/P Supplier Tax Distribution Detail
APSTDS | ApTaxDistSum | A/P Supplier Tax Distribution Summary
CSHTDD | CshTaxDistrDet | Cash Book Tax Distribution Detail
CSHTDH | CshTaxDistrHdr | Cash Book Tax Distribution Header

On a SQL Server based system the ISSUE008.SQL script adds the new columns for these files.

On both C-ISAM and SQL Server based systems the company control file will be updated to the new issue number so that you can log in as normal.

Details of file changes

The following details all the database changes for issue 008.

Tables with line number changed from decimal(5,0) to char(5). See Article General Ledger Line Numbers

Table name | Column | ISAM file | ISAM field
GenAltCurCtl | NextLineCur | GENALC | GENALC-CNXT
GenAltCurCtl | NextLinePrv | GENALC | GENALC-PNXT
GenAltCurDet | Line | GENALD | GENALD-LIN
GenEntriesCtl | NextEntryNum | GENENC | GENENC-NXT
GenEntriesDetail | EntryNumber | GENEND | GENEND-ENT
GenMaster | NextLine | GENMST | GENMST-CNXT
GenMaster | NextLinePyr | GENMST | GENMST-PNXT
GenCopyMaster | NextLine | GENCMS | GENCMS-CNXT
GenCopyMaster | NextLinePyr | GENCMS | GENCMS-PNXT
GenTransaction | Line | GENTRN | GENTRN-LIN
GenCopyTrans | Line | GENCTR | GENCTR-LIN

Tables requiring ISAM conversion and with extra columns in SQL Server

Table name | New columns | Data type | ISAM file
ApTax2DistSum | TaxCode9-TaxCode26 | char(1) | APSD2C
ApTax2DistSum | TaxValue9-TaxValue26 | decimal(14,2) | APSD2C
ApTax2DistDet | TaxCode9-TaxCode26 | char(1) | APSD2D
ApTax2DistDet | TaxValue9-TaxValue26 | decimal(14,2) | APSD2D
ApTaxDistDet | TaxCode9-TaxCode26 | char(1) | APSTDD
ApTaxDistDet | TaxValue9-TaxValue26 | decimal(14,2) | APSTDD
ApTaxDistDet | TaxRetSubmitted | char(1) | APSTDD
ApTaxDistDet | YearRetSubmitted | decimal(4,0) | APSTDD
ApTaxDistDet | MthRetSubmitted | decimal(2,0) | APSTDD
ApTaxDistSum | TaxCode9-TaxCode26 | char(1) | APSTDS
ApTaxDistSum | TaxValue9-TaxValue26 | decimal(14,2) | APSTDS
CshTaxDistrDet | TaxCode9-TaxCode26 | char(1) | CSHTDD
CshTaxDistrDet | TaxAmtEntries9-TaxAmtEntries26 | decimal(14,2) | CSHTDD
CshTaxDistrDet | TaxRetSubmitted | char(1) | CSHTDD
CshTaxDistrDet | YearRetSubmitted | decimal(4,0) | CSHTDD
CshTaxDistrDet | MthRetSubmitted | decimal(2,0) | CSHTDD
CshTaxDistrHdr | TaxCode9-TaxCode26 | char(1) | CSHTDH
CshTaxDistrHdr | TaxAmtEntries9-TaxAmtEntries26 | decimal(14,2) | CSHTDH

Tables with renamed column names

Table name | ISAM file | Old column name | New column name
AdmEvent | ADMEVE | Parameter | EventParameter
AdmMultimediaCtl | ADMMMC | Parameter | ObjectParameter

New tables

ISAM file | Table name | Description
ADMLCL | {ISAM only} | Admin License Class Master
ADMLI1 | {ISAM only} | Admin License Imported XML Temp File
ADMLI2 | {ISAM only} | Admin License Configuration Temp File
ADMLI3 | {ISAM only} | Admin License Class Temp File
ADMLIC | {ISAM only} | Admin License Configuration Master
ADMLIX | {ISAM only} | Admin License Imported XML file
GENCCD | GenCopyCommitDet | Copy of G/L Commitment Detail
GENCCM | GenCopyCommitment | Copy of G/L Commitment
GENPCD | GenCommitDetail | G/L Commitment Detail
GENPCM | GenCommitment | G/L Commitment
INVDOI | {ISAM only} | Inventory Inspection Document
INVDOX | {ISAM only} | Inventory Inspection Document - Serials
MRPWIN | MrpWipInspect | MRP Snapshot WIP Inspection Control
SORRTD | SorRouteDetail | Sales Order Route Detail
SORRTH | SorRouteSoHeader | Sales Order Route Order Header
SORRTL | SorRouteSoDetail | Sales Order Route Order Detail
SORRTM | SorRouteMaster | Sales Order Route Master
TBLEUD | TblSaDelTerms | S/A Intrastat Delivery Terms
TBLEUN | TblSaTransactNat | S/A Intrastat Nature of Transaction
WIPINC | WipInspect | WIP Inspection Control
WIPIND | WipInspectDet | WIP Inspection Detail
WIPINS | WipInspectSerial | WIP Inspection Serials

The table below lists the new columns added to existing tables

In C-ISAM all the fields reside in previous FILLER fields.

Table name | Column | Data type | ISAM file | ISAM field
ApSupplier | DefTaxCode | char(1) | APSMST | APSMST-TAX-CODE
ApSupplier | DeliveryTerms | char(3) | APSMST | APSMST-DELTRMS
ApSupplier | TransactionNature | decimal(3,0) | APSMST | APSMST-NATURE
ArCustomer | DeliveryTerms | char(3) | ARSMST | ARSMST-DELTRMS
ArCustomer | TransactionNature | decimal(3,0) | ARSMST | ARSMST-NATURE
ArCustomer | DeliveryTermsC | char(3) | ARSMST | ARSMST-DELTRMSC
ArCustomer | TransactionNatureC | decimal(3,0) | ARSMST | ARSMST-NATUREC
ArCustomer | RouteCode | char(10) | ARSMST | ARSMST-ROUTE
BomOperations | TransferQtyOrPct | char(1) | BOMOPS | BOMOPS-TRF-PCT
BomOperations | TransferQtyPct | decimal(10,3) | BOMOPS | BOMOPS-TRF-QTY
GenEntriesDetail | CommitmentFlag | char(1) | GENEND | GENEND-COMMIT
GenJournalCtl | Currency | char(3) | GENJNC | GENJNC-CUR
InvControl | NextInsDocNum | decimal(9,0) | INVCTL | INVCTL-NXT-INS
InvControl | NextRejDocNum | decimal(9,0) | INVCTL | INVCTL-NXT-REJ
InvControl | NextScrDocNum | decimal(9,0) | INVCTL | INVCTL-NXT-SCR
InvJournalCtl | WipInspectCtl | char(15) | INVJNC | INVJNC-WIP-INSLDG
InvJournalDet | CommitmentFlag | char(1) | INVJND | INVJND-COMMIT
InvWhControl | WipInspectGlCode | char(15) | INVWHC | INVWHC-WIP-INSLDG
InvWhControl | Nationality | char(3) | INVWHC | INVWHC-NATION
PorEcReceipts | ArrivalNationality | char(3) | PORECV | PORECV-NAT-ARR
PorEcReceipts | TrnMonth | decimal(2,0) | PORECV | PORECV-MONTH
QotOperation | TransferQtyOrPct | char(1) | QOTOPS | QOTOPS-TRF-PCT
QotOperation | TransferQtyPct | decimal(10,3) | QOTOPS | QOTOPS-TRF-QTY
MrpJobMaster | OrigDueDate | datetime | MRPJOB | MRPJOB-ORG-DUE
MrpJobAllLab | TransferQtyOrPct | char(1) | MRPLAL | MRPLAL-TRF-PCT
MrpJobAllLab | TransferQtyPct | decimal(10,3) | MRPLAL | MRPLAL-TRF-QTY
MrpQotOperation | TransferQtyOrPct | char(1) | MRPQOP | QOTOPS-TRF-PCT
MrpQotOperation | TransferQtyPct | decimal(10,3) | MRPQOP | QOTOPS-TRF-QTY
MrpQotSoDetail | OrigShipDateAps | datetime | MRPQSD | MRPQSD-ORGSHP-APS
MrpSugWipCtl | NextInspReference | decimal(10,0) | MRPSJC | MRPSJC-INS-NXT
MrpSugJobMaster | OrigDueDate | datetime | MRPSJM | MRPSJM-ORG-DUE
MrpSugJobAlLab | TransferQtyOrPct | char(1) | MRPSLL | MRPSLL-TRF-PCT
MrpSugJobAlLab | TransferQtyPct | decimal(10,3) | MRPSLL | MRPSLL-TRF-QTY
MrpSoDetail | OrigShipDateAps | datetime | MRPSOD | MRPSOD-ORGSHP-APS
SorCancelled | TaxCode | char(1) | SORCAN | SORCAN-TAX-CODE
SorChanges | TaxCode | char(1) | SORCHG | SORCHG-TAX-CODE
SorControl | NextRmaNumber | decimal(8,0) | SORCTL | SORCTL-NEXT-RMA-NO
SorDetail | OrigShipDateAps | datetime | SORDET | SORDET-ORGSHP-APS
SorDetailRep | OrigShipDateAps | datetime | SORRDT | SORRDT-ORGSHP-APS
WipControl | NextInspReference | decimal(10,0) | WIPCTL | WIPCTL-INS-NXT
WipJobAllLab | TransferQtyOrPct | char(1) | WIPLAL | WIPLAL-TRF-PCT
WipJobAllLab | TransferQtyPct | decimal(10,3) | WIPLAL | WIPLAL-TRF-QTY
WipMaster | OrigDueDate | datetime | WIPMST | WIPMST-ORG-DUE

See also

What's new about SYSPRO 6.0 issue 008, SYSPRO 6.0 issue 007 database changes, SYSPRO 6.0 issue 006 database changes, Fields changed since Encore 4.0


SYSPRO 6.0 Issue 007 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 006 and SYSPRO 6.0 Issue 007. It includes both SQL Server and C-ISAM changes.

On a SQL Server based system remember to run ISSUE007.SQL against each company database using Query Analyzer.

On a C-ISAM based system remember to re-index the files with new indexes.

Important Changes

The following tables have new indexes and must be re-indexed on C-ISAM systems.

Table name | ISAM file | New key | New key parts
PorSupStkInfo | PORSST | Stock code | StockCode, Supplier

There are two new tables.

Table name | ISAM file | Description
GenCategory | GENCAT | G/L Revaluation Category
SalProductClassDes | SALPDS | S/A Product Class Description

The table below lists the new columns added to existing tables

In C-ISAM all the fields reside in previous FILLER fields.

Table name | Column | Data type | ISAM file | ISAM field
ArCustomer | CompanyTaxNumber | char(15) | ARSMST | ARSMST-CTAXNO
ArCustomerBal | NumZeroInvoices | decimal(7,0) | ARSBAL | ARSBAL-ZEROINV
ArCustomerBal | NumZeroDays | decimal(12,0) | ARSBAL | ARSBAL-ZERODAYS
ArSalesMove | ForInvoiceValue | decimal(14,2) | ARSMOV | ARSMOV-FAMT
ArSalesMove | InvoiceCurrency | char(3) | ARSMOV | ARSMOV-MC-CUR
ArPayHistory | LocalPayValue | decimal(14,2) | ARSPAY | ARSPAY-LVAL
ArTrnDetail | Version | char(3) | ARSSTD | ARSSTD-VER
ArTrnDetail | Release | char(3) | ARSSTD | ARSSTD-REL
BomMachine | WorkCentre | char(6) | BOMMCH | BOMMCH-WRK
BomMachine | ShiftId | char(16) | BOMMCH | BOMMCH-SHIFT
BomEmployee | ShiftId | char(16) | BOMEMP | BOMEMP-SHIFT
BomWorkCentre | CellId | char(16) | BOMWRK | BOMWRK-CELL
CfgComponent | LCalculatedFlag | char(1) | CFGCOM | CFGCOM-L-CALC
GenAltCurDet | PriorRate | decimal(12,6) | GENALD | GENALD-P-RATE
GenAltCurDet | PriorValue | decimal(14,2) | GENALD | GENALD-P-VAL
GenAltCurDet | Comment2 | char(20) | GENALD | GENALD-CMT2
GenCopyMaster | RevalCategory | char(2) | GENCMS | GENCMS-CAT
GenCopyMaster | AltCurIndicator | char(1) | GENCMS | GENCMS-ACIND
GenCopyMaster | GlUnitOfMeasure | char(10) | GENCMS | GENCMS-OUM
GenCopyTrans | Comment2 | char(20) | GENCTR | GENCTR-CMT2
GenEntriesDetail | AddReference2 | char(20) | GENEND | GENEND-CMT2
GenMaster | RevalCategory | char(2) | GENMST | GENMST-CAT
GenMaster | AltCurIndicator | char(1) | GENMST | GENMST-ACIND
GenMaster | GlUnitOfMeasure | char(10) | GENMST | GENMST-OUM
GenTransaction | Comment2 | char(20) | GENTRN | GENTRN-CMT2
InvMaster | DateStkAdded | datetime | INVMST | INVMST-DATE-ADD
InvWareouse | DateWhAdded | datetime | INVWHS | INVWHS-DATE-ADD
MdnMaster | CompanyTaxNo | char(15) | MDNMST | MDNMST-CTAXNO
MdnMasterCons | CompanyTaxNo | char(15) | MDNCMS | MDNCMS-CTAXNO
MdnMasterRep | CompanyTaxNo | char(15) | MDNRMS | MDNRMS-CTAXNO
MdnMasterRepCon | CompanyTaxNo | char(15) | MDNPMS | MDNPMS-CTAXNO
MrpQotSoMasterHdr | CompanyTaxNo | char(15) | MRPQSH | MRPQSH-CTAXNO
MrpSoMasterHdr | CompanyTaxNo | char(15) | MRPSOH | MRPSOH-CTAXNO
MrpWarehouse | DateWhAdded | datetime | MRPWHS | MRPWHS-DATE-ADD
PorScrapRejectIns | PoLine | decimal(4,0) | PORREJ | PORREJ-PO-LINE
PorSupStkInfo | AltDocPrice | decimal(15,5) | PORSST | PORSST-ALT-DOC-PRC
QotSoMasterHdr | CompanyTaxNo | char(15) | QOTSOH | QOTSOH-CTAXNO
SalControl | DateLastUpdate | datetime | SALCTL | SALCTL-UPD-DATE
SorMaster | CompanyTaxNo | char(15) | SORMST | SORMST-CTAXNO
SorMasterRep | CompanyTaxNo | char(15) | SORRMS | SORRMS-CTAXNO

See also

What's new about SYSPRO 6.0 issue 007, SYSPRO 6.0 issue 006 database changes, Fields changed since Encore 4.0


SYSPRO 6.0 Issue 006 Database Changes

This topic covers the database changes between SYSPRO 6.0 Issue 005 and SYSPRO 6.0 Issue 006. It includes both SQL Server and C-ISAM changes.

On a SQL Server based system remember to run ISSUE006.SQL against each company database using Query Analyzer.

On a C-ISAM based system remember to re-index the files with new indexes.

Important Changes

The column called Route has changed from decimal(1,0) to char(1) in the following tables.

Table name | Column | ISAM file | ISAM field
AbcAnalysis | Route | ABCANL | ABCANL-ROUTE
InvWhControl | Route | INVWHC | INVWHC-ROUTE
MrpJobMaster | Route | MRPJOB | MRPJOB-ROUTE-CDE
MrpSugJobMaster | Route | MRPSJM | MRPSJM-ROUTE-CDE
WipMaster | Route | WIPMST | WIPMST-ROUTE-CDE

In addition the following tables have new indexes.

Table name | ISAM file | New key | New key parts
ApSupplier | APSMST | Name | SupplierName, Supplier
ArCustStkXref | ARSSCX | Stock code | StockCode, Customer, CustStockCode
InvWhControl | INVWHC | Description | Description, Warehouse
PorSupStkInfo | PORSST | Catalogue | SupCatalogueNum, Supplier, StockCode
PorSupStkInfo | PORSST | Supplier | Supplier, SupCatalogueNum, StockCode
PorSupStkInter | PORSTI | Stock code | StockCode, SupCatalogueNum, Supplier

There is a single new table.

Table name | ISAM file | Description
MrpJobClass | MRPCLS | MRP Snapshot of Job Classification

The table below lists the new columns added to existing tables

In C-ISAM all the fields reside in previous FILLER fields.

Table name | Column | Data type | ISAM file | ISAM field
ApListChDet | ManualChRef | char(9) | APSCHD | APSCHD-PMT-REF
ApInvoice | ManualChRef | char(9) | APSINV | APSINV-MCR
ArCstStkPrc | UnitDiscFlag1 | char(1) | ARSLPP | ARSLPP-DFLGA
ArCstStkPrc | UnitDiscValue1 | decimal(14,2) | ARSLPP | ARSLPP-DVALA
ArCstStkPrc | UnitDiscFlag2 | char(1) | ARSLPP | ARSLPP-DFLGB
ArCstStkPrc | UnitDiscValue2 | decimal(14,2) | ARSLPP | ARSLPP-DVALB
AssetMaster | GroupCodePrevMth | char(2) | ASSMST | ASSMST-GRP-PM
BpoDetail | Version | char(3) | BPODET | BPODET-M-VER
BpoDetail | Release | char(3) | BPODET | BPODET-M-REL
BomStructure | IncludeFromJob | char(8) | BOMMST | BOMMST-FROM-JOB
BomStructure | IncludeToJob | char(8) | BOMMST | BOMMST-TO-JOB
CfgComponent | Version | char(3) | CFGCOM | CFGCOM-VER
CfgComponent | Release | char(3) | CFGCOM | CFGCOM-REL
CfgComponent | CreateSubJob | char(1) | CFGCOM | CFGCOM-SUB-JOB
EccRevHistoryCost | SubContractCost | decimal(15,5) | ECCCST | ECCCST-SUB-COST
EccStructure | IncludeFromJob | char(8) | ECCSTR | ECCSTR-FROM-JOB
EccStructure | IncludeToJob | char(8) | ECCSTR | ECCSTR-TO-JOB
IntEdiInvExtra | DiscPct | decimal(4,2) | INTINE | INTINE-TDISC-PER
IntEdiInvExtra | DueDays | decimal(3,0) | INTINE | INTINE-TDISC-DUED
IntEdiInvExtra | DiscDays | decimal(3,0) | INTINE | INTINE-TDISC-DSCD
IntEdiInvExtra | InvoiceDueDate | datetime | INTINE | INTINE-INV-DUE
IntEdiInvExtra | TotalMass | decimal(14,6) | INTINE | INTINE-TOT-MASS
IntEdiInvExtra | TotalVolume | decimal(14,6) | INTINE | INTINE-TOT-VOL
IntEdiInvExtra | TotalQuantity | decimal(11,3) | INTINE | INTINE-TOT-QTY
InvJournalDet | Version | char(3) | INVJND | INVJND-VER
InvJournalDet | Release | char(3) | INVJND | INVJND-REL
InvInspectSerial | Version | char(3) | INVINS | INVINS-VER
InvInspectSeria | Release | char(3) | INVINS | INVINS-REL
InvMovements | Version | char(3) | INVMOV | INVMOV-VER
InvMovements | Release | char(3) | INVMOV | INVMOV-REL
InvMaster | JobClassificaion | char(4) | INVMST | INVMST-JOB-CLS
InvMaster | SubContractCost | decimal(15,5) | INVMST | INVMST-SUB-COST
InvStockTakeSerial | Version | char(3) | INVSTE | INVSTE-VER
InvStockTakeSerial | Release | char(3) | INVSTE | INVSTE-REL
InvSerialHead | Version | char(3) | INVSTH | INVSTH-VER
InvSerialHead | Release | char(3) | INVSTH | INVSTH-REL
InvWarehouse | SubContractCost | decimal(15,5) | INVWHS | INVWHS-SUB-COST
InvWhatIfCost | WhatIfSubContCost | decimal(15,5) | INVWIF | INVWIF-SUB-COST
MdnDetailLotCons | LotExpiryDate | datetime | MDNCLO | MDNCLO-EXP-DAT
MdnDetailLot | LotExpiryDate | datetime | MDNDLO | MDNDLO-EXP-DAT
MdnDetailLotRepCon | LotExpiryDate | datetime | MDNPLO | MDNPLO-EXP-DAT
MdnDetailLotRep | LotExpiryDate | datetime | MDNRLO | MDNRLO-EXP-DAT
MrpJobMaster | MrpFromJob | char(8) | MRPJOB | MRPJOB-FROM-JOB
MrpJobMaster | MrpToJob | char(8) | MRPJOB | MRPJOB-TO-JOB
MrpQotNonStock | JobClassification | char(4) | MRPQNO | MRPQNO-JOB-CLS
MrpQotStructure | ComVersion | char(3) | MRPQST | MRPQST-VER
MrpQotStructure | ComRelease | char(3) | MRPQST | MRPQST-REL
MrpSugJobMaster | MrpFromJob | char(8) | MRPSJM | MRPSJM-FROM-JOB
MrpSugJobMaster | MrpToJob | char(8) | MRPSJM | MRPSJM-TO-JOB
MrpWarehouse | SubContractCost | decimal(15,5) | MRPWHS | MRPWHS-SUB-COST
QotNonStock | JobClassification | char(4) | QOTNON | QOTNON-JOB-CLS
QotStructure | ComVersion | char(3) | QOTSTR | QOTSTR-VER
QotStructure | ComRelease | char(3) | QOTSTR | QOTSTR-REL
SorDeliveryPerf | SalesOrderLine | decimal(4,0) | SORPER | SORPER-ORD-LIN
SorDeliveryPerf | Operator | char(6) | SORPER | SORPER-OPERATOR
SorDeliveryPerf | TrnDate | datetime | SORPER | SORPER-DATE
SorDeliveryPerf | TrnTime | decimal(8,0) | SORPER | SORPER-TIME
WipJobClass | ClassJobPrefix | char(5) | WIPCLS | WIPCLS-JOB-PREFIX
WipJobClass | ClassJobSuffix | decimal(8,0) | WIPCLS | WIPCLS-JOB-SUFFIX
WipMaster | MrpFromJob | char(8) | WIPMST | WIPMST-FROM-JOB
WipMaster | MrpToJob | char(8) | WIPMST | WIPMST-TO-JOB
WipScrapDet | Version | char(3) | WIPSCD | WIPSCD-VER
WipScrapDet | Release | char(3) | WIPSCD | WIPSCD-REL

See also

What's new about SYSPRO 6.0 issue 006, Fields changed since Encore 4.0


Fields changed since Encore 4.0

List of fields that have increased in size since Encore 4.0

Field | Scrollable | From | To
Stock code | Yes | 15 | 30
Inventory price code |  | 1 | 2
A/P Discount code |  | 1 | 2
A/R discount code |  | 1 | 2
A/R Terms code |  | 1 | 2
A/P Terms code |  | 1 | 2
S/o commission code |  | 1 | 2
Coded shipping instructions |  | 1 | 2
S/O Order type |  | 1 | 2
Price code currency xref |  | 1 | 2
A/P Invoice number |  | 9 | 20
A/P Invoice reference |  | 9 | 30
Inventory transaction reference |  | New field for 5.0 | 30
BOM Sequence number |  | 2 | 6
Inventory mass |  | 4.3 | 6.6
A/R email address | Yes | 25 | 50
A/P email address | Yes | 25 | 50
Buyer email address | Yes | 25 | 50
Requisition email address | Yes | 25 | 50
Customer p/o number |  | 14 | 30
A/R tax exempt |  | 13 | 30
A/R and A/P contact name | Yes | 20 | 40
A/R remittance fax contact | Yes | 30 | 40
A/P remittance fax contact | Yes | 30 | 40
A/R price code matrix |  | 26 | 52
S/O ship instructions |  | 15 | 30
P/O ship instructions |  | 14 | 30
S/O special instructions |  | 9 | 30
Version |  | 2 | 3
Release level |  | 2 | 3
Qty pricing |  | 5 breaks | Unlimited


Data Dictionary Overview

Introduction

The Data dictionary is a core component of SYSPRO. It contains a complete definition of the data structures for both C-ISAM and SQL format data. This information includes all the files, fields, keys and comments traditionally held in the Record Layouts. In addition to C-ISAM information, SQL Server specific information is held – this includes Table and Column names that do not normally form part of C-ISAM based Record Layouts.

The Data Dictionary system consists of a set of data files shipped as part of SYSPRO that contain the standard SYSPRO data definitions together with a Data Dictionary Manager that is a set of programs that allows import, export and viewing of the Data Dictionary definition.

Why have a Data Dictionary?

Apart from actually storing the complete data definition, the Data Dictionary is tightly integrated into the development and deployment of SYSPRO.

In previous versions of Encore (3.2/4.0) there were record layouts with a .MAC extension that contained the C-ISAM data definition. The name of the physical data file, record layout, record area, fields and keys were all generated historically using a style that was difficult to remember, and due to it’s limitations, was not easy to extend when new files or modules were to be added.

The design of the SYSPRO Data Dictionary provides a high degree of consistency in the naming conventions. This helps developers, support personnel and end-users alike in working with SYSPRO data. In addition, the Data Dictionary Manager provides many services that assist in automation of various data based tasks. For example there is a utility that allows you to browse the Data Dictonary (DDSBFI) and then to zoom into the physical data using a completely generic browser.

From SYSPRO 6.1 there is a Data Dictionary Validation tool that assists developers in creating new record layouts or updating your own layouts to ensure that the conventions used are valid.

What is the Data Dictionary used for?

The Data Dictionary is used, together with the Data Dictionary Menu program (DDSMEN), to provide many development and support services. These include:

  • Importing of Record Layouts allows the Data Dictionary to be generated accurately and quickly using existing data definitions.

  • Export of Record Layouts allows accurate and consistent creation of Record Layouts for inclusion into your Net Express source code.

  • Export of copybooks containing the Net Express SELECT clauses (SEL files) mean that consistent naming and accurate definition of keys is provided.

  • Export of copybooks containing all the C-ISAM file logic (CFL files) for a file mean that the developer can concentrate on the business logic required instead of having to remember the C-ISAM I/O statement syntax.

  • The source code to SQL file handler programs can be generated that provide transparent access to SQL using the standard file logic copybooks (CFL files). This allows existing C-ISAM based applications to work virtually seamlessly in a SQL Server environment.

  • A generic file browser has been provided (DDSBFI) that allows simple access to any standard SYSPRO data (C-ISAM or SQL). This assists in the development and testing process and can be used by support personnel for viewing end-user data.

  • Migration utilities between C-ISAM and SQL allow companies to move their data easily and accurately from the traditional C-ISAM format to SQL.

  • Re-indexing of C-ISAM files can be automated using the data definition stored within the data dictionary. This is done by exporting IMPFIL.IMP from the data dictionary.

  • A SQL Server diagnostic utility (IMPDG6) uses the Data Dictionary to compare the physical database with the expected Data Dictionary definition. This can assist support personnel in identifying problems with a database configuration that is not performing as expected.

  • The Report Writer Data Dictionary can be generated directly from the SYSPRO Data Dictionary providing accurate and consistent data definition. The Report Writer uses the SQL Server Table and Column names for accessing data. The Report Writer Data Dictionary can therefore always be accurate and up-to-date.

  • The Data Dictionary system has an export function that is deigned to assist in developing ODBC catalogues. This semi-automation means that the ODBC catalogues are always accurate and up-to-date for those users wishing to access C-ISAM data using ODBC compliant systems.

  • For developers SQL scripts can be generated that allow definition of the tables, columns, keys and constraints. These scripts can be applied to a database during the development and/or implementation process.

How is the Data Dictionary shipped with SYSPRO?

The Data Dictionary files are stored in the base\dd directory (on the server in a client/server environment).

These files are named DDS???.DAT and DDS???.IDX (DDS??? and DDS???.idx on Unix)

The main data dictionary menu program is called DDSMEN and can be run using File, Run, DDSMEN or added to your Favorites menu.

Note that DDSMEN is designed for developers (and can also be used by support personnel). You should prevent access to this program for regular operators.

For developers and support personnel there is a Data Dictionary Viewer program called DDSBFI. This allows the Data Dictionary to be browsed and you can select a single table and zoom into it's definition or alternatively invoke a generic data browser allowing you to browse any C-ISAM/SQL table. Again it is important that you strictly limit who can use DDSBFI on an end-users site.

Note that these utilities have been extensively re-engineered for SYSPRO 6.0 issue 010.

Importing Existing Record Layouts

Once you have defined your own Record Layout you should first use the Data Dictionary Validation function to verify that the proposed record layout changes are appropriate and conform to the standard conventions.

Once validated successfully you are ready to use the Data Dictionary Import function to read and verify your record layouts. Your Record Layout must conform to the SYSPRO Data Dictionary Conventions for the import to be successful.

When imported successfully your data definitions will be included into the Data Dictionary and can be used just as any other data definition. This includes using DDSBFI to view the data definitions and the physical data and all the other developer generation capabilities.

See also

Data Dictionary Import, Data Dictionary Export, Data Dictionary Conventions, Data Dictionary Validation, Record Layouts, Reindexing, IMPFIL.IMP


Data Dictionary Import

SYSPRO SDK

Data Dictionary

Data Dictionary Validation and Import

Introduction

The process of creating a new Data Dictionary, or adding your custom files to the standard Data Dictionary, is to first edit and store one or more Record Layouts in a subfolder below the standard source folder.

For example create a folder named \rnd60\source\proposed.

Then use the Data Dictionary Validation program (DDSVAL) to verify your proposed record layout changes. It provides a detailed list of any non-conformance which need to be corrected before continuing with the import process.

Once validated you can copy your proposed record layouts to the standard copybook folder (e.g. \rnd60\source\copy60) and then to use the Data Dictionary Import function which reads and verifies the Record Layout against the Data Dictionary Conventions and, if valid, adds it to the Data Dictionary.

Creating a Record Layout

A Record Layout is a text file that describes a SYSPRO data file. It contains a C-ISAM data definition and usually also contains information describing a parallel SQL Server table.

Remember that the majority of SYSPRO data definitions allow developers to code their application for both C-ISAM and SQL Server environments and therefore the Data Dictionary must contain both sets of information.

See the Record Layout topic for the file naming conventions and file location to be used.

Use the Net Express IDE, or your favorite text editor, to create your record layout and store it in the proposed copybook directory. See the topic Data Dictionary Conventions for the rules and conventions to be used when creating or maintaining a record layout.

For example you may have a record layout named CUSMST.MAC that describes your Custom Master file - it might be stored as:

\RND60\SOURCE\PROPOSED\CUSMST.MAC

Once you have saved the record layout in the correct proposed copybook folder you are ready to use the Data Dictionary Validation function.

The process of Validating a Record Layout

Load SYSPRO and run the Data Dictionary Validation program (DDSVAL).

After a few seconds this program displays three panes. The 'Folders' pane on the left lists subfolders below the source folder (it excludes some obvious non-copybook folders such as source\binsrc and source\fh).

For example if you created a folder named \rnd60\source\proposed then you should see the folder 'proposed' in the 'Folders' pane below the standard COPY60 folder.

Click on the folder (e.g. 'Proposed'). After a few seconds you should see a list of all the proposed copybooks that reside in the folder selected. It shows all copybooks with a MAC, MAI, MAT, MAS extension. At this time the validation program has read the first few lines of each proposed copybook to locate the description, file code and table name (if any). It will show a message 'Not yet validated' against each record layout.

Select 'Validate All' from the toolbar to start the validation process.

The validation process performs extensive tests on each of the proposed record layouts to ensure that they strictly conform to all the best practices and conventions used internally at SYSPRO.

If there are any non-conformances then the list of record layouts will be sorted, showing the non-conformances first and highlighted by an icon.

To view each non-conforming record layout click on the listview row containing the non-conformance and one or more detail message will be shown in the 'Messages' pane. A detailed list of errors will be shown together with a description of the non-conformance. If there are more than one error then the system will display each error separately. However it should be noted that some errors can cause subsequent 'correct' lines to be shown as errors. If you are not sure then correct the errors in the sequence that they are shown and try validating again.

Note that some exceptions to the strict rules are listed in the text file IMPDDS.IMP. In addition, if required, you can add your own exceptions to some of the rules by creating a CUSDDS.IMP in the custom program folder. This includes being able to define a list of column names that must be accepted 'as is', and listing alternate indexes that do not contain all the parts from the primary key. The IMPDDS.IMP text file has comments that are designed to be self-explanatory.

Hint - When running this program in a standalone environment you can click on the hyperlinked record layout name to edit the record layout in Notepad. Simply make the change required, save the record layout, exit Notepad and rerun the 'Validate All' function.

Change report

When the 'Validate All' function returns no errors in any of the record layouts then the 'Change Report' toolbar button is enabled. This function is designed to create a comma separated (Change_Report.CSV) text file that can be read into Excel to summarize the changes between the proposed record layouts and the existing ones (from the existing data dictionary). This change report capability is primarily designed for use internally at SYSPRO but you may find it useful for your own development environment.

Once you are satisfied that the data dictionary validation program has validated all your proposed record layouts successfully then you are ready to use the Data Dictionary Import function.

Before using the import function copy the record layouts from the proposed folder to the standard COPY60 folder.

The process of Importing a Record Layout

Load SYSPRO and run the Data Dictionary Menu program (DDSMEN). Select Functions > Import...

Note there is field that shows the location from where the record layouts will be imported. If this is incorrect you should verify the SRCNEW= entry in the TOOLKIT.INI file stored in the base folder. After you edit this entry and save the file you must exit back to the menu and re-run DDSMEN.

Select the record layout(s) to be imported - usually just entering the name of your single file (e.g. CUSMST). You do not have to supply the file extension as the system will search for all valid file extensions (MAC, MAI, MAT, MAS).

Select 'Import...' and accept the confirmation.

Importing a single record layout should take only a second or two - sometimes slightly longer for larger definitions.

The import function validates the record layout and, if any errors are found, a report will be generated. A brief message explaining the problem will be included on the report. Only the first error is shown as often one error causes many others. You should immediately correct the problem in the record layout and re-import the same file. If you have previously used the Data Dictionary Validation program (recommended) then it's unlikely that you should receive any error messages during the import process.

Note that if an error is detected during the import the Data Dictionary definition for that file is incomplete - hence the reason for correcting and re-importing it immediately.

If the Import function is successful it simply returns back to the Import dialog box (with a short beep). This allows you to quickly import several record layouts.

When you exit the import dialog box the last file imported will already be selected on the main listview.

See also

Data Dictionary Overview, Data Dictionary Conventions, Record Layout, TOOLKIT.INI


Data Dictionary Export

Introduction

The Data Dictionary has a complete definition of SYSPRO data structures, including both C-ISAM and, where relevant, SQL Server information. These complete data definitions allow utilities to be developed to generate support files that allows developers to automate or semi-automate various tasks.

For example the Data Dictionary can be used to generate a SQL Server script to add a table - including all the column and key definitions.

In most cases the files exported are created in a sub-directory called NEW beneath the copybook directory. For example if you have the copybook directory called

\RND60\SOURCE\COPY60

then most of the export functions export files to

\RND60\SOURCE\COPY60\NEW

You must ensure that this directory exists and that you have appropriate permissions to create files in this directory.

To use any of the Data Dictionary Export functions you load SYSPRO, run the Data Dictionary Menu program (DDSMEN) and select Functions, Export...

This loads the Export Dialog box. You can select All, Range, Single or from a List of files. The functions available vary depending on whether you select All files or not.

The remainder of this topic describes each of the Export functions available.

Record layouts (MAC)

This function is used to generate Record Layouts.

The Record Layouts are generated in the NEW sub-directory. Record Layouts have a MAC, MAI, MAS or MAT file extension.

The Record Layouts are generally moved to the copybook folder (i.e. up one level) before they are included in a Net Express program - or can be used by the Data Dictionary Import function.

The reason that the copybooks are exported to the NEW sub-directory is to avoid accidentally overwriting an existing Record Layout.

Select copybooks (SEL)

This function is used to generate copybooks defining Net Express SELECT statements. These copybooks are designed to be included into your Net Express program to define the file and keys in a consistent way.

The SELECT copybooks are generated in the NEW sub-directory. SELECT copybooks have a SEL file extension.

The SELECT copybooks are generally moved to the copybook folder (i.e. up one level) before they are included in a Net Express program.

File logic (CFL)

This function is used to generate copybooks defining Net Express File Logic statements. These copybooks are designed to be included into your Net Express program to define File Logic procedures in a consistent way.

The File Logic copybooks are generated in the NEW sub-directory. File Logic copybooks have a CFL file extension.

This function requires the templates named DDSCFL?.TEM in the SOURCE directory.

The File Logic copybooks are generally moved to the copybook folder (i.e. up one level) before they are included in a Net Express program.

Generic file copybook (FILE.PRO and FILE.WRK)

This function is used to generate two copybooks that are automatically included in every Net Express program.

The FILE.PRO copybook contains conditional compilation statements that identify each Record Layout included in your source code (by looking for a 78 level field) and automatically add File Logic (CFL) copybooks to allow you to access the file in a consistent way. This copybook is automatically included in the PROBEGIN.PRO copybook.

The FILE.WRK copybook contains conditional compilation statements that identify each Record Layout included in your source code (by looking for a 78 level field) and automatically add a field that defines the file name. This copybook is automatically included in the STANDARD.WRK copybook.

The FILE.PRO and FILE.WRK copybooks are generated in the NEW sub-directory.

The FILE.PRO and FILE.WRK copybooks are generally moved to the copybook folder (i.e. up one level) before they are included in a Net Express program.

List of files (IMPFIL.IMP)

This function is used to generate the IMPFIL.IMP file that defines the list of files. This file is shipped as part of the standard SYSPRO system in the program directory.

Many SYSPRO programs use IMPFIL.IMP (instead of the Data Dictionary) when they require a list of files. For example the Reindexing Utility uses IMPFIL.IMP to identify the files that are to be Reindexed, their names and the key definitions. This file is used for historical purposes.

IMPFIL.IMP is generated in the program directory.

In versions of SYSPRO prior to SYSPRO 6.1 the file IMPFIL.IMP was generated in the SOURCE folder. From SYSPRO 6.1 onwards the file IMPFIL.IMP is generated into the PRG folder.

The file IMPFIL.IMP must already exist in the PRG folder so that the existing version number of the file can be retained, or incremented, depending on the 'increment version' checkbox.

If you are generating your own file layouts then you can manually edit IMPFIL.IMP, remove the standard SYSPRO file definitions and then rename the file to CUSFIL.IMP. This can be used to re-index your own files.

ODBC Export (SYSPRO60.UFD)

This function is used to generate a file called SYSPRO60.UFD. This file can be used by a developer attempting to create an ODBC catalogue. You require appropriate ODBC development software to import the UFD file.

The UFD file is generated in the NEW sub-directory.

This topic does not discuss the details of how you use the UFD file to create an ODBC catalogue.

Limitations when exporting a .UFD file for creating an ODBC catalogue

The ODBC drivers currently are limited to UPPERCASE for Table names therefor the export translates these types of object to uppercase

The maximum character field supported is 254 bytes. Fields that exceed this length will only use the first 254 bytes

Generate inter-file linkages

The Data Dictionary Import automatically generates links between files using the key definitions and column names to determine logical links. This function is not commonly required.

However this function can be used to rebuild the inter-files links.

Generate SQL based DD files

The Data Dictionary Import automatically generates the SQL Server based Data Dictionary files. These are parts of the Data Dictioanry that contain SQL information. This function is not commonly required.

However this function can be used to rebuild the SQL based Data Dictionary files.

File handlers (FH??????.CBL)

This function is used to generate the source code for SQL Server File Handlers.

SQL Server File Handlers are generated in a FH sub-directory beneath the SOURCE directory. SQL Server File Handlers start FH and use the six character file code followed by '.CBL' extension.

This function requires the template DDSMFH.TEM in the SOURCE directory.

After you have generated a SQL Server File Handler you typically load a Net Express command prompt, changed to SOURCE\FH and use the COMPILE batch file to compile the file handler.

For example after generating the INVMST file handler - load a Net Express Command Prompt and type:

CD SOURCE\FH

COMPILE FHINVMST

The object code is generated in the BASE\FH directory.

Create table script (TABLE.SQL)

This function is designed to be used by developers to generate a SQL script used to add a table to your SQL Server database.

This function creates a script called TABLE.SQL in the SOURCE directory.

If you have selected two or more tables to be generated then the SQL logic to create all the tables will reside in the single script file TABLE.SQL.

Table and column filter

Note that there is an entry field labelled 'Table and column filter' below the 'Create table script' checkbox. This will default to the current version of SYSPRO software being used (e.g. '6.1').

The create table script function will default to only exporting tables that have the prefix entered at this entry field. This can be useful when you have imported a number of new record layouts for the new version of SYSPRO and marked the record with the new version number.

For example the record layout CSHCOL.MAC defines a new file for SYSPRO 6.1. Note that the record definition 'CSHCOL-REC' is prefixed with '6.1'.

6.1 01 CSHCOL-REC.

03 CSHCOL-KEY.

05 CSHCOL-MODEL PIC X(10).

* SQL=Model

* Model code

05 CSHCOL-COL PIC 9(3).

* SQL=Collector

* Collector number

When this record layout is imported the data dictionary will record the '6.1' prefix. When using the 'Create table script' option the export will default to only generating table definitions for tables marked with the '6.1' prefix. i.e. only the new tables.

If you wish to prevent a filter on tables so that all selected tables are generated then enter a value of 'ALL' in the filter.

Create keys script (KEYS.SQL)

This function is designed to be used by developers or support personnel to generate a SQL script used to drop existing keys for a table and then to re-apply the keys.

This function creates a script called KEYS.SQL in the SOURCE directory.

If you have selected two or more files to be generated then the SQL logic to create all the tables will reside in the generated file KEYS.SQL.

Create column script (COLUMN.SQL)

This function is designed to be used by developers to generate a SQL script used to add a columns to your SQL Server database.

This function creates a script called COLUMN.SQL in the SOURCE directory.

If there are two or more columns to be created then the code to add all the relevant columns will be inserted into the single script file COLUMN.SQL.

Table and column filter

Note that there is an entry field labelled 'Table and column filter' below the 'Create column script' checkbox. This will default to the current version of SYSPRO software being used (e.g. '6.1').

The create column script function will default to only exporting columns that have the prefix entered at this entry field. This can be useful when you have imported one or more record layouts for the new version of SYSPRO and marked the new columns with the new version number.

For example the record layout INVMST.MAC contains 3 new columns for SYSPRO 6.1. Note that these fields are prefixed with '6.1'.

6.1 03 INVMST-SEC-CODE PIC X(20).

* SQL=StorageSecurity

* Storage security code

6.1 03 INVMST-HAZ-CODE PIC X(20).

* SQL=StorageHazard

* Storage hazard

6.1 03 INVMST-COND-CODE PIC X(20).

* SQL=StorageCondition

* Storage condition

When this record layout is imported the data dictionary will record the '6.1' prefixes. When using the 'Create column script' option the export will default to only generating column definitions for columns marked with the '6.1' prefix. i.e. only the new columns.

If you wish to prevent a filter on columns so that all columns for the selected tables are generated then enter a value of 'ALL' in the filter.

Bulk copy export (BCP)

This function was used for historical purposes and is not currently used.

See also

Data Dictionary Overview, Data Dictionary Import, Data Dictionary Export, Record Layouts, PROBEGIN.PRO, TOOLKIT.INI


Data Dictionary Conventions

Introduction

This topic describes how to create a Record Layout. It includes various rules that must be adhered to and a number of conventions to get the best out of the Data Dictionary.

A sample custom record layout is shown below. This is not a standard SYSPRO Record Layout but is a valid custom record layout that is used to illustrate the detailed explanations below.

All Record Layout definitions must be valid Net Express source code. They must conform to Net Express rules for data definition.

Sample Record Layout

      **************************************************************

      *                          SYSPRO                            *

      *  Copyright (c) 1994-2010 SYSPRO Ltd. All rights reserved.  *

      **************************************************************

      *  Record layout : CUSMST.MAC                                *

      *  Description   : Custom Barcode Master                     *

      *  @(#) Version  : 6.1.000                                   *

      *  Last updated  : 2010/01/05 11:30                          *

      *  Record length :    90                                     *

      *  Key length    :    30                                     *

      *  Data file     : $d$cCUSMST$e                              *

      *  Module        : CUS                                       *

      *  Table name    : CusBarcode                                *

      **************************************************************

      *  Alternate idx : CUSMST-IDX-BARCODE      Barcode           *

      *                : CUSMST-BARCODE          Barcode           *

      *                : CUSMST-STK              Stock code        *

      **************************************************************

      ** This file describes the barcode information for a stock code

      ** and is used by a custom application

6.1    01  CUSMST-REC.

           03  CUSMST-KEY.

               05  CUSMST-STK     PIC X(30).

      *                                     SQL=StockCode

      *                                     Stock code

           03  CUSMST-BARCODE     PIC X(15).

      *                                     SQL=Barcode

      *                                     Barcode

           03  CUSMST-PRICE       PIC S9(12)V9(2).

      *                                     SQL=Price

      *                                     Price

           03  CUSMST-DATE        PIC 9(8).

      *                                     SQL=LastUpdated

      *                                     Date price last updated

           03  CUSMST-ACTIVE      PIC X.

      *                                     SQL=ActiveFlag

      *                                     Active flag

      *                                     Y - Yes

           03  FILLER             PIC X(22).

      *

       78  CUSMST-MAC-RLN VALUE 90.

       78  CUSMST-MAC-KLN VALUE 30.

       78  CUSMST-MAC-FLG VALUE 1.

File code

Each file definition is assigned a 6 character file code. The first 3 characters typically use a module code (such as INV, GEN, BOM) and the last 3 characters are a brief mnemonic describing the file.

In the above example 'CUS' stands for Custom and 'MST' is the master file.

It is strongly recommended that you do not use the three character module codes used by standard SYSPRO modules as we may use the same file code in future versions on SYSPRO. The standard list of file code/modules can be viewed in the IMPMOD.IMP file.

Before creating a record layout it is suggested that you create an entry the custom version of IMPMOD.IMP (called CUSMOD.IMP). You should define the three character program prefix and also the 3 character data file prefix - tigether with a table prefix for the 'module'. See the following example:

; CUSMOD.IMP - List of Custom SYSPRO Modules

;

; Copyright (c) 1994-2010 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.1.000 Last updated : 2010/01/05 11:30

;

;Mod Program prefix modules

;-- ------------------------------

CUS Custom Development

;Isam Table

;Mod Data file prefix modules prefix

;-- ------------------------------ -----

CUS Custom Development Cus

; End of CUSMOD.IMP

Comment header

The comment header is one of the most important part of the Record Layout definition.

During the Data Dictionary Validation and Import process this structured information is used to describe the generic information about the file, such as the description, C-ISAM specific information, such as the Record length and Key lengths and SQL Server specific information, such as the Table name.

      **************************************************************

      *                          SYSPRO                            *

      *  Copyright (c) 1994-2010 SYSPRO Ltd. All rights reserved.  *

      **************************************************************

      *  Record layout : CUSMST.MAC                                *

      *  Description   : Custom Barcode Master                     *

      *  @(#) Version  : 6.1.000                                   *

      *  Last updated  : 2010/01/05 11:30                          *

      *  Record length :    90                                     *

      *  Key length    :    30                                     *

      *  Data file     : $d$cCUSMST$e                              *

      *  Module        : CUS                                       *

      *  Table name    : CusBarcode                                *

      **************************************************************

      *  Alternate idx : CUSMST-IDX-BARCODE      Barcode           *

      *                : CUSMST-BARCODE          Barcode           *

      *                : CUSMST-STK              Stock code        *

      **************************************************************

      ** This file describes the barcode information for a stock code

      ** and is used by a custom application

Record layout

You must define the name of the Record Layout including the file extension.

See the Record Layout naming conventions for more information.

Description

This field describes the file being defined by the Record Layout.

The file description can be up to 40 characters in length.

It is recommended that you use initial capitals for each major word.

@(#) Version

You can use this field to store up to 7 characters of version information.

This field is used for documentary purposes only.

Last updated

This field is generated when using the Data Dictionary Export function and is discarded during the import process.

This field is used for documentary purposes only.

Record length

This field describes the total ISAM record length. It is mandatory for all Record Layouts.

A maximum record length of 3000 is supported.

From SYSPRO 6.1 the record length defined here will be verified during the Data Dictionary Validation and Import process with the total of all the field lengths in the Record Layout and an error will be given if they do not match. The reason that this is done is to help prevent accidentally changing the record length of an existing record layout.

Key length

This field must describe the total primary key length for MAC, MAI and MAT files. The field is not used for sequential (MAS) Record Layouts.

A maximum key length of 200 is supported.

From SYSPRO 6.1 the primary key length defined here will be verified during the Data Dictionary Validation and Import process with the total of primary key length in the Record Layout and an error will be given if they do not match. The reason that this is done is to help prevent accidentally changing the record length of an existing record layout.

Data file

This field describes a parameterized version of the C-ISAM disk file name. The parameters are described in the EXPAND-WW-FILE-NAME function.

Note that the normal functions to build file names used by most SYSPRO Net Express programs do not use this field, however several generic programs that use the Data Dictionary do use this field together with the EXPAND-WW-FILE-NAME function.

Module

This field describes a 3 character module code.

This field is used for documentary purposes only.

Table name

This field describes the SQL Server table name. This field must be defined for MAC Record Layouts and can optionally be described for MAI files.

The table name can consist of up to 18 characters and must be a valid SQL Server table name. You should avoid SQL Server reserved words.

Typically camel case table names are used (e.g. InvMaster or ApSupplier or AssetType)

Table names must be unique.

You should use '{temp}' for temporary (MAT) files.

If this Record Layout describes a Sequential file (MAS) and this file is read (or imported) then you should use '{import}' if it is written (or exported) then you should use '{export}'.

If you do not wish to defined a table name for MAI or MAS files then use '{none}'

Alternate idx

The alternate index section allows you to optionally describe any alternate indexes that are to be defined for the Record Layout. These can be described for MAC, MAI and MAT record layouts.

Each alternate index must include all the fields from the primary file.

You can describe up to a maximum of 11 alternate indexes per file.

Each alternate key can consist of no more than 20 key parts.

First line of alternate index section

The first line of the alternate index section describes the name of the index.

The field definition must start at column 26 (CUSMST-IDX-BARCODE in the above example). It must start with the 6 character file code followed by a '-IDX-' string followed by a short mnemonic describing the index. The key name can be up to 20 characters in length.

The first line of the alternate index section from column 50 describes the alternate key. You can use up to 18 characters.

Second and subsequent lines of alternate index section

Each of the second and subsequent lines of the alternate index section describe a field that makes up the alternate index key parts. The field names start at column 26 and must match one of the fields defined in the record layout - you may not use group fields in this definition - rather specify each individual field.

Note that the field descriptions stating at column 50 do not have to be defined - they are generated when you use the Data Dictionary Export function.

Each alternate key can consist of no more than 20 key parts. Until SYSPRO 6.1 the limit was 8 key parts per alternate key.

Additional Record Layout Header Comments

Additional Record Layout comment lines can be applied immediately beneath the comment header block.

In this case you must start each comment line with two asterisks.

Record and Primary key definition

The record definition and key definition must be defined immediately below the comment header block.

See the following code fragment from our example file definition.

6.1     01  CUSMST-REC.

           03  CUSMST-KEY.

               05  CUSMST-STK     PIC X(30).

Field version information

Every field being described can have an optional 6 character string that is typically blank but can be used to assign version or other information.

This field is used for documentary purposes only but can be used as selection criteria when using some of the Data Dictionary Export functions.

The above example shows a string '6.1' at the beginning of the record definition. Other recent examples include:

6.1    * SYSPRO 6.1

6.0.12 * SYSPRO 6.0 Issue 010 SP2

6.0.11 * SYSPRO 6.0 Issue 010 SP1

6.0.10 * SYSPRO 6.0 Issue 010

6.0.9  * SYSPRO 6.0 Issue 008

Record definition

The record definition must start with '01' followed by the record name.

The record name must consist of the 6 character file code followed by the string '-REC.'

The above example shows a record definition of '01 CUSMST-REC.'

You can only define a single record definition per record layout (i.e. only one '01' level field).

Primary key definition

The primary key definition must start with '03' followed by the key name.

The key name must consist of the 6 character file code followed by the string '-KEY.'

The primary key definition must have subordinate fields that define the key.

The above example shows a primary key definition of '03 CUSMST-KEY.'

You can only define a single primary key definition per record layout.

The primary key definition can consist of up to 11 key parts (remember that an alternate key can consist of up to 20 key parts).

You must not define an OCCURS clause in the primary key.

Field definition

Each field in the Record Layout consists of a level number (generally '03' upwards) followed by a field name followed by a picture definition. This must conform to Net Express rules for data definitions.

The Data Dictionary convention is to describe the field more fully using comments that immediately follow the field name. The field name together with the associated comments all form part of the field definition for the purposes of the Data Dictionary.

You can defined up to 1000 fields per Record Layout. Other limits may restrict the maximum number of fields.

6.1    01  CUSMST-REC.

           03  CUSMST-KEY.

               05  CUSMST-STK     PIC X(30).

      *                                     SQL=StockCode

      *                                     Stock code

           03  CUSMST-BARCODE     PIC X(15).

      *                                     SQL=Barcode

      *                                     Barcode

           03  CUSMST-PRICE       PIC S9(12)V9(2).

      *                                     SQL=Price

      *                                     Price

           03  CUSMST-DATE        PIC 9(8).

      *                                     SQL=LastUpdated

      *                                     Date price last updated

           03  CUSMST-ACTIVE      PIC X.

      *                                     SQL=ActiveFlag

      *                                     Active flag

      *                                     Y - Yes

           03  FILLER             PIC X(22).

Level number

The level numbers must conform to the rules of Net Express data definition.

Most fields use a level number of '03' except for subordinate fields that can have higher numbers.

Field name

The field name consists of the 6 character file code followed by a dash ('-') followed by a short field description.

The field name can be up to 21 characters in length.

Picture string

The picture string consists of the string 'PIC ' followed by a data type definition.

Alphanumeric fields consist of X(xx) where xx is the number of characters in the string. The largest alphanumeric field supported is 3000 characters. It is recommended that no character in the ASCII character set less than a space is stored in an alphanumeric field (no escape characters, control characters, tabs, line feeds etc).

Unsigned numeric integer fields consist of 9(xx). where xx is the number of integers. A maximum of 12 integers is supported. Signed numeric integers are defined as S9(xx).

Unsigned decimal numeric fields consist of 9(xx)V9(y) where xx is the number of integers and y is the number of decimals. A maximum of 12 integers and a maximum of 6 decimals are supported. Signed decimal numeric fields are defined as S9(xx)V9(y).

Date fields consist of 9(8) and are always stored as CCYYMMDD. All dates must be valid with the exception of a zero value. This can be used as a special value.

All picture strings are completed with a full stop ('.').

How does the data dictionary import decide whether a PIC 9(8) field is a date, time or 8-digit numeric field, such as the next automatic job number?

The Data Dictionary import has some hard-coded logic to decide how to handle a PIC 9(8) field.

- If the Net Express field name ends with the string 'TIME' or 'TIM' then it is assumed to be a time. For example ADMJOB-ON-TIME.

- If the Net Express field name ends with the strings 'NEXT-JOB', 'NEXT-QOT', 'NEXT-RMA', 'JOB-SUFFIX', 'TOOLSET-CON' or 'ADMB2C-XMLFILE' then the fields are assumed to be an 8-digit numeric field.

- If neither or the above is true then the field is assumed to be a date.

Defining GUID Picture strings

From SYSPRO 6.0 Issue 010 SP1 you can define a GUID in your record layout by defining a field as PIC X(16) and the name of the field must contain the string 'GUID' or the Column name can contain the word 'Guid'.

SQL Server column name

Immediately following the field definition you can define a comment field that describes the SQL Server column name. This is mandatory for MAC Record Layouts and optional for MAI files.

This definition consists of a string that starts 'SQL=' at column 45 immediately followed by the SQL Server column name.

The column name can consist of up to 18 characters and must be a valid SQL Server column name. You should avoid SQL Server reserved words.

Typically camel case column names are used (e.g. Customer or StockCode or SalesOrder)

The column name must be unique per table.

It is strongly recommended that you use consistent column naming conventions as various SYSPRO utilities and other applications can take advantage of this consistency.

Note that when a fields forms part of a table (i.e. the fields occurs a number of times) then you must add a hash ('#') at the end of the column name. Multiple column names will be generated automatically by the system. For example if a column occurs 3 times with the name 'Balance#' then the columns Balance1, Balance2 and Balance3 will be generated. The total length must not exceed 18 characters. A maximum of 999 occurrences are supported. Other limits may apply before this limit is reached.

Field comments

You can define multiple field comments against each field.

Fields comments start at column 45 and can each have a maximum length of 35 characters (30 characters prior to SYSPRO 6.0 issue 010).

The first field comment has a special purpose. It is used throughout the Data Dictionary system as the field description. It is recommended that the first field comment always describes the field - even if it summarizes the complete description.

If the field is a flag or indicator then the possible values should be described using the field comments. See the above example for the column named 'ActiveFlag'.

78 levels

Each Record Layout must have a 78 level indicator flagging that the Record Layout has been used in the Source code.. The string is exactly the same regardless of whether the Record Layout is MAC, MAI, MAT or MAS.

This 78 level must consist of the 6 character file code followed by the string '-MAC-FLG VALUE 1.'

This indicator is ignored during the Data Dictionary Validation and Import process and is generated by the Record Layout export function.

The Record Layout must have this 78 level indicator when including the Record Layout in a Net Express program. It is used to ensure that the appropriate CFL copybook is correctly included in your source code.

Record length and key length 78 levels

In addition to the indicator (e.g. 78 INVMST-MAC-FLG VALUE 1.) from SYSPRO 6.0 issue 010 onwards each Record Layout also has two other 78 levels defining the record length and primary key length.

For example the Inventory Master Record Layout (INVMST.MAC) has the following 78 levels for SYSPRO 6.1.

78 INVMST-MAC-RLN VALUE 835.

78 INVMST-MAC-KLN VALUE 30.

78 INVMST-MAC-FLG VALUE 1.

General notes

All Record Layout definitions must be valid Net Express source code. They must conform to Net Express rules for data definition.

Note that not all valid Net Express source code data definitions can be used by the SYSPRO Data Dictionary. For example:

  • you may not use any other picture strings other than those mentioned above

  • you cannot use REDEFINES statements

  • you cannot have OCCURS clauses in a primary or alternate key

  • you can only have a single level of OCCURS

You can define comments that are not associated with a specific field. This is done by prefixing the field comment with two asterisks and defining up to 77 characters of comment (this can be seen in the standard Record Layout SORDET.MAC).

Shared inventory information

A number of files in the Inventory Control module use a shared inventory id rather than the current company id.

For a C-ISAM file this means that the shared id is used as the prefix to the physical file name and in a SQL Server environment the tables used will reside in the company database defined for the shared company.

For more information see the topic Shared Inventory Files.

See also

Data Dictionary Overview, Data Dictionary Import, Data Dictionary Export, Record Layout, Shared Inventory Files, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16


Record Layout

SYSPRO SDK

Data Dictionary

Record Layouts

Introduction

A Record Layout is a text file that describes a SYSPRO data file - it is typically imported into the SYSPRO Data Dictionary. It contains a C-ISAM data definition and usually also contains information describing a parallel SQL Server table.

The majority of SYSPRO data definitions allow developers to code their application for both C-ISAM and SQL Server environments and therefore Record Layouts and the Data Dictionary contains both sets of information.

Important: see the Data Dictionary Conventions topic for the rules and conventions to be applied before importing a Record Layout into the Data Dictionary.

Record Layout Location

Record Layouts are designed to be stored beneath the SOURCE directory in a sub-directory called COPY?? where ?? is the version of SYSPRO.

For example SYSPRO 6.0 Record Layouts are assumed to reside in:

\RND60\SOURCE\COPY60

The Data Dictionary Import will expect the Record Layouts to be stored in this location. If you wish to use an alternate path then you should edit the SRCCPB= entry in TOOLKIT.INI.

Record Layout Naming Conventions

Record Layouts must have a 6 character file name followed by a 3 character extension.

The name is made up of the following parts:

MMMXXX.MA?

Where:

MMM is a three character module code as defined in IMPMOD.IMP - data file prefix section.

XXX is a three character mnemonic identifying the file usage within the module.

MA? is a three character file extension indicating the type of data storage - see table below.

Extension

Examples

Usage

MAC

INVMST.MAC

ARSMST.MAC

SORMST.MAC

A MAC file extension indicates that when running in a SQL Server environment this Record Layout represents a SQL Server Table whereas in a C-ISAM environment this Record Layout represent a C-ISAM file.

This type of Record Layout must contain both SQL Server and C-ISAM information.

MAI

ADMOPR.MAI

ADMCTL.MAI

REPMST.MAI

A MAI file extension indicates that this Record Layout represents a file that is always stored in C-ISAM format regardless of the company configured data storage medium.

This type of Record Layout must define C-ISAM information but can also defined SQL Server information if is to be accessed using the Data Dictionary Viewer, Reporting Services, Report Writer or from ODBC.

MAT

CFGTM1.MAT

ADMKIT.MAT

A MAT file extension indicates that this Record Layout represents a Temporary C-ISAM file that is created by one program and used by a subsequent program. When these programs have finished using the Temporary file they will remove it.

See the topic Temporary Files for naming convention used for these temporary files.

This type of Record Layout only contains C-ISAM information.

MAS

ADMINI.MAS

ADMPRG.MAS

A MAS file extension indicates that this Record Layout represents a sequential ASCII text file. It either defines a text file that is to be read (or imported) or a text file that is to be created (or exported).

The IMP files have definitions with a MAS extension.

This type of Record Layout only contains C-ISAM type information.

MAM

ADMCTLGL.MAM

REPMST10.MAM

REPMST20.MAM

A MAM file extension is different from the other Record Layout extensions in that it is NOT imported into the Data Dictionary. These are redefinitions of other Record Layouts - usually MAI files.

These files have an 8 character file name followed by '.MAM'. The First 6 characters are the file being redefined and the last 2 characters are a mnemonic of the type of redefinition.

For example ADMCTLGL.MAM is the 'GL' redefinition of the ADMCTL.MAI file. Often the mnemonic used is a two character Record Type - part of the main file definition key.

This type of Record Layout only contains C-ISAM type information and can contain any legal Net Express syntax for data definitions. These are NOT imported into the data dictionary.

Record Layout Conventions

Record Layouts must be valid Net Express data definitions as they are included into Net Express source code.

In addition SYSPRO have a number of rules and conventions that must be adhered to if you want to be able to use the Data Dictionary Validation and Import function.

Before creating a Record Layout it is strongly recommended that you read the Data Dictionary Conventions topic.

Record Layout 78 levels

From SYSPRO 6.0 issue 010 onwards all record layouts have three 78 level fields appended to the end of the data definition. 78 level fields are constants that can be used by the programmer to code programs generically. You can also add conditional compilation statements to detect the existence of these constants.

For example the Inventory Master Record Layout (INVMST.MAC) contains the following 78 levels for issue 010. Note that the suffixes is always includes MAC even if the file has a MAI, MAS or MAT file extension.

78 INVMST-MAC-RLN VALUE 835.

78 INVMST-MAC-KLN VALUE 30.

78 INVMST-MAC-FLG VALUE 1.

INVMST-MAC-RLN

The constant suffixed with MAC-RLN is the ISAM record length in bytes.

INVMST-MAC-KLN

The constant suffixed with MAC-KLN is the ISAM primary key length in bytes.

INVMST-MAC-FLG

The constant suffixed with MAC-FLG is a constant that can be used in conditional compilation statements to detect the existence of the Record Layout. For example the following code fragment is taken from the standard SYSPRO copybook FILE.PRO.

$if INVMST-MAC-FLG DEFINED

COPY "INVMST.CFL".

$end

See also

Data Dictionary Overview, Data Dictionary Conventions, Data Dictionary Import, Temporary file, IMP files, TOOLKIT.INI


SQL Server and ISAM Differences

Background

SYSPRO is designed to run on both C-ISAM and SQL Server. The data storage mechanism is defined at run-time at the company level.

The programs typically make use of standard functions to access any data. These standard data access functions will either issue regular C-ISAM statements (such as OPEN, READ, WRITE, REWRITE, CLOSE etc) or call a SQL file handler which issues an appropriate SQL statement (SELECT, INSERT, UPDATE etc).

The functions (such as PERFORM INVMST-READ, PERFORM INVMST-WRITE, PERFORM INVMST-REWRITE) are designed to work virtually identically regardless of whether you are using SQL Server or a C-ISAM run-time environments.

However there are some differences and the remainder of this topic will explain them. In each case XXXXXX represents one of the 6 character file codes available in SYSPRO.

XXXXXX-BUILD-AND-OPEN-IO-COMER (plus other build and open statements)

Purpose

The BUILD-AND-OPEN-IO-COMER function is commonly used at the start of a program to initiate access to a SYSPRO file.

It does this by generating the physical file name based on system and company parameters - for example the Inventory Master file name could be C:\Syspro\Data\1INVMST.DAT - where '1' is the company id. It then opens the file for reading and writing and if any errors occur it displays an error message and to exit the program by branching to the ENDJOB paragraph.

If the file does not exist it will be created silently.

Differences on a SQL Server environment

In a SQL Server environment the file name built is a pseudo file name that contains various parameters relating to the table to be accessed. The pseudo file name is defined by the copybook SQLFILE.WRK.

Note that the first three characters of the file name always start 'SQL' - this is an internal indicator that the run time environment is SQL Server.

There is no equivalent of opening an ISAM file in a SQL Server environment. Any OPEN statement causes the SQL file handler (FHXXXXXX.GNT in base\fh) to be invoked and it will initialize some parameters. Note that it will always return a STAT-OK status.

Therefore the last part of the statement (COMER) will always return ok.

Due to this difference you cannot use an OPEN statement to verify whether a table exists, to create a table or to test whether you have appropriate permission to access a table. This will be performed the first time you access the table using one of the other file handling statements.

XXXXXX-READ

Purpose

The READ function is used to perform a random read using the primary key.

It will return the status and (if STAT-OK) the record area (XXXXXX-REC) will contain the data for that record.

Any record lock for that key will be ignored.

Differences on a SQL Server environment

In a SQL Server environment the READ function will cause the SQL File handler to build and execute a SELECT statement returning all the standard SYSPRO columns for the selected primary key.

If successful the SELECT will return the record area (XXXXXX-REC) exactly the same as the ISAM READ. Note that if any column has a NULL value then the returned value will be SPACES for alpha fields and ZEROS for numeric and date fields.

At the time that the READ statement is performed the integrity of the system will be verified. ie. whether you have permissions to access the database and table, whether the table exists, whether all the standard columns exist and that their datatypes are correct. All of these parameters are only verified during the READ. Therefore there are many more things that can fail during a READ than on an ISAM system.

Any row lock for the key will be ignored - ie. the SELECT statement is issued with a WITH (NOLOCK) phrase.

However largely the SQL Server READ performs identically to an ISAM READ.

XXXXXX-READ-LOCK

Purpose

The READ-LOCK function is used to perform a random read using the primary key and to attempt to acquire a record lock.

It will return the status and (if STAT-OK) the record area (XXXXXX-REC) will contain the data for that record.

If the record is locked by another user then the status STAT-LCK will be returned. You can detect this and display an appropriate message or retry as applicable (see READ-WAIT).

If the read was successful then a record lock will be acquired and should be released later using an UNLOCK or COMMIT.

Differences on a SQL Server environment

In a SQL Server environment the READ-LOCK function will cause the SQL File handler to build and execute a SELECT statement returning all the standard SYSPRO columns for the selected primary key.

If successful the SELECT will return the record area (XXXXXX-REC) exactly the same as the ISAM READ. Note that if any column has a NULL value then the returned value will be SPACES for alpha fields and ZEROS for numeric and date fields.

As the READ-LOCK statement is expecting to acquire a row lock on the selected key you must perform this statement from within a transaction (you must have previously issued a BEGIN-TRANSACTION function). In this case:

- The read lock will acquire a row lock on the specified key

- If the row is already locked by another user the system will block (wait) for the row to be released

Note that the ability of the READ-LOCK to acquire a row lock was only added for SYSPRO 6.1.

However largely the SQL Server READ-LOCK performs identically to an ISAM READ-LOCK as long as it is issued from within a transaction.

XXXXXX-READ-WAIT

Purpose

The READ-WAIT function is identical to the READ-LOCK function except that it will wait indefinitely if the record is already locked.

Therefore it cannot return a STAT-LCK status.

All other capabilities are identical to the READ-LOCK.

Differences on a SQL Server environment

In a SQL Server environment the READ-WAIT works identically to the READ-LOCK function on SQL Server. This is because the READ-LOCK function on SQL Server always waits for the lock to be released if it is already locked. Please take note about the other comments against the READ-LOCK on SQL Server.

Note that the ability of the READ-WAIT to acquire a row lock was only added for SYSPRO 6.1.

However largely the SQL Server READ-WAIT performs identically to an ISAM READ-WAIT as long as it is issued from within a transaction.

XXXXXX-START-GE (and START-GT, START-LE, START-LT)

Purpose

All the START functions are used to position the current record pointer to a key greater than or equal to, greater than, less than or equal to or less than the specified key value.

The most common use is to setup an initial key then perform the START-GE function. Immediately after this the program will use the READ-NEXT function to read successive subsequent records until some value changes or until the end of file.

The START functions return a STAT-INVALID-KEY status if the condition is not met (eg. there is no key greater than or equal to the initial key). No other file statuses should be tested.

Differences on a SQL Server environment

In a SQL Server environment the START functions do not access the physical table. The file handler simply records the condition (GE, GT, LE, LT) and the initial key. A subsequent READ-NEXT will cause the table to be accessed and a row to be fetched.

Due to this difference the START will always return STAT-OK and therefore you must not use the START to verify whether an item exists.

As long as you issued a READ-NEXT immediately after issuing a START the logic is very similar to the ISAM START and READ-NEXT combination.

However remember that the START always returns STAT-OK and the READ-NEXT is the statement that initiates access to the rows in a table.

XXXXXX-READ-NEXT

Purpose

The READ-NEXT function is used to fetch a single record from the file based on the current record pointer (usually setup using a START). In addition it increments the current record pointer so that a subsequent READ-NEXT will return the next record in the file.

It will return the status and (if STAT-OK) the record area (XXXXXX-REC) will contain the data for that record.

The STAT-AT-END status should be used to test for the end of file.

You must assume that the record area is undefined when any status other that STAT-OK is returned.

Differences on a SQL Server environment

In a SQL Server environment the START functions do not access the physical table. The file handler simply records the condition (GE, GT, LE, LT) and the initial key. A subsequent READ-NEXT will cause the table to be accessed and a row to be fetched.

Due to this difference the START will always return STAT-OK and therefore you must not use the START to verify whether an item exists.

As long as you issued a READ-NEXT immediately after issuing a START the logic is very similar to the ISAM START and READ-NEXT combination.

However remember that the START always returns STAT-OK and the READ-NEXT is the statement that initiates access to the rows in a table.

Another difference worth noting is that as the SQL Server system is more sophisticated the READ-NEXT may return other file errors. Therefore it is best practice after testing for the STAT-AT-END condition that you also PERFORM COMER. For example if the table has missing columns the READ-NEXT will return the information about the missing columns and the COMER will display this information. If you simply test for STAT-AT-END then you will not identify this condition and the program will not perform as expected and could hang/loop.

Note that the READ-PREVIOUS functions work in a similar way to the READ-NEXT and will not be covered separately.

XXXXXX-WRITE

Purpose

The WRITE function is used to insert a new record into the file using a unique primary key.

You should use the COMER function to verify that the record was added successfully.

Differences on a SQL Server environment

In a SQL Server environment the WRITE function will cause the SQL File handler to build and execute an INSERT statement adding all the standard SYSPRO columns for the selected primary key.

Note that if any date column has a zero value '00000000' then it will be inserted as a NULL value - all other alphanumeric and numeric columns will have their values inserted. Only dates will cause a NULL to be inserted.

All SQL Server rules will be honored during the insert - including datatype validation, check constraints, unique indexes and any foreign key constraints. For this reason it is best practice to use the COMER function to verify that the record was added successfully.

However largely the SQL Server WRITE performs identically to an ISAM WRITE.

XXXXXX-REWRITE

Purpose

The REWRITE function is used to update an existing record in the file using the primary key.

You should use the COMER function to verify that the record was updated successfully.

Differences on a SQL Server environment

In a SQL Server environment the REWRITE function will cause the SQL File handler to build and execute an UPDATE statement updating all the standard SYSPRO columns for the selected primary key.

Note that if any date column has a zero value '00000000' then it will be updated to have a NULL value - all other alphanumeric and numeric columns will have their values inserted. Only dates will cause a NULL to be inserted.

All SQL Server rules will be honored during the update - including datatype validation, check constraints, unique indexes and any foreign key constraints. For this reason it is best practice to use the COMER function to verify that the record was update successfully.

However largely the SQL Server REWRITE performs identically to an ISAM REWRITE.

XXXXXX-CLOSE

Purpose

The CLOSE function is used to indicate to the system that access to the file has completed.

You should not test the file status code after a CLOSE.

It is permissible to perform a CLOSE function if the file is already closed.

Typically you should use the PERFORM CLOSE-ALL-FILES as a quick and easy way to close all files accessible by your program. This is usually performed in the ENDJOB paragraph.

Differences on a SQL Server environment

In a SQL Server environment the CLOSE function will cause the SQL File handler to release any resources back to the system that may have been used by previous SQL statements. This includes closing any cursors that may have been created.

However largely the SQL Server CLOSE performs identically to an ISAM CLOSE.

See also

SQL Server tuning code, Transaction Processing, Transferring data between ISAM and SQL, SQL Server Tuning more than 300 columns, COMER, ENDJOB, SQL-GENERATE-WHERE-LIKE


SQL Server tuning

SYSPRO SDK

SQL Server

Performance Tuning SQL Server for SYSPRO

Introduction

This topic is aimed at improving the performance of SYSPRO running on SQL Server. As a developer you should also see the section about tuning your code for getting the best performance from SQL Server.

There are several sections:

  • Introduction

  • Status of tuning for SQL Server

  • Hardware and SQL Server tuning

  • Tuning SYSPRO programs

  • Transferring data from ISAM to SQL and back

Note that the SYSPRO Help has a section that is aimed at System Administrators and Support Personnel. This help file details many issues related to setup and maintenance of SQL Server for a SYSPRO installation. It is recommended that you read the contents of the SYSPRO Help for all SQL topics thoroughly.

Background

SYSPRO is designed to run on both C-ISAM and SQL Server. The data storage mechanism is defined at run-time at the company level. The programs make use of standard functions to access any data. These standard data access functions will either issue regular C-ISAM statements (such as OPEN, READ, WRITE, REWRITE, CLOSE etc) or call a SQL file handler which issues an appropriate SQL statement (SELECT, INSERT, UPDATE etc).

Whilst this is extremely powerful as the same programs can run on the two completely different data storage mechanisms, there is some level of optimization that can be performed to access the SQL Server system more efficiently.

If you want to see how to add access your own custom tables see the topic SQL Server User Defined Tables.

What approaches are available?

There are several things that can be done to improve the performance of a program running on SQL Server. These generally involve re-coding parts of the application to build and issue an efficient SQL statement. Generally a good understanding of the program function is required to get the best out of SQL Optimization.

A number of facilities have been developed to allow an efficient SQL statement to be issued. The benefits of optimizing the SQL statements include:

  • When selecting data a WHERE condition can be accurately specified to ensure that only the data required is returned by SQL Server. This is especially useful when only a small number of rows in the table are to be selected. For example only active sales orders or jobs.

  • When selecting data only the columns required can be specified to minimize the amount of data being returned by SQL Server.

  • It is possible to select data using the database JOIN function that allows two or more tables to be effectively treated as one for reporting or selection purposes. Using an effective JOIN between two or more tables can have the biggest effect on system performance.

  • When updating data it is possible to be able to issue one SQL statement to update many rows. For example to be able to reset a column to have a zero value. This often has a dramatic effect on the performance of global file changes.

Probably the biggest difference that can be done to improve a report or batch type program is to use the table JOIN to avoid the SQL file handler having to open, process and close multiple cursors.

Transaction Positing and Queries

Some programs create temporary files with selected criteria. The building of these temporary files can be improved. Example of this include the A/R Invoice Query program (IMPBIN) that shows a consolidated Invoice/Payments browse. The temporary file created by the join of both of these tables has been improved.

This section of the document is aimed at getting the best performance out of SQL Server

Whilst some SYSPRO programs can have their performance improved for SQL Server it is important to ensure that SQL Server is setup optimally.

This section is designed to provide guidelines about how to get the best level of performance from a SYSPRO system running on Microsoft SQL Server. Remember to read the SYSPRO Help SQL information as this contains thorough information relating to setup and maintenance of SQL Server.

  • Performance checklist

  • SQL Server tuning

  • General SQL Server notes

  • Frequently Asked Questions

  • What affects the performance of SYSPRO on SQL Server?

  • Why does SYSPRO on SQL Server run slower that Encore 4.0?

  • What version of Windows should I be using?

  • What version of SQL Server should I be using?

  • Can I or should I add indexes?

Performance checklist

This is a checklist of areas that affect performance of SYSPRO on SQL Server. It is recommended that each point is verified in sequence.

Server and Client computers

As with most performance issues the general speed and configuration of the Server and Client computers together with the Network can have the most dramatic affect on performance. A faster computer will generally provide the better performance and the more memory it has often improves the situation.

Over time any recommendations made are quickly superceded and therefore the following are general recommendations.

Generally SQL Server is more sensitive to available memory and disk speed than processor speed. However a faster processor will definitely help.

The majority of the following points assume that for a given hardware configuration you wish to tune the software running on those computers.

  • What Windows version
    Whilst a comparison of versions of Windows is not in the scope of this document it is clear that specific versions of SQL Server run more effectively on specific versions of Windows. For example in the past SQL Server 2000 running on Windows 2000 runs quicker that SQL Server 7.0 on Windows NT. In some cases the difference is substantial. We recommend that a test bed is used to verify the performance. Since this article has been authored subsequent versions of both Windows server platforms and SQL Server have been released. It is suggested that you consider later versions as they often improve performance and add significant functionality and security improvements.

  • SQL Server 2000 Service pack 3 and 4
    We have noticed that a number of features added to SQL Server 2000 SP3 have improved the performance of several SYSPRO programs. It appears that this occurs when the first column of the primary clustered key is defined as a 'decimal' column. SYSPRO Sales Transation and Journal tables have the year or journal number as the first column and so are affected by this. As an example of the performance improvement - an Invoice register report running through a table of 2 million rows that previously took 1 hour 30 minutes was reduced to 10 minutes. As above we recommend that you always consider the later versions of SQL Server. See the Support Zone for the latest support platforms and any notes and FAQ's. Subsequent to this information SQL Server 2005 has overall improved performance from SQL Server 2000.

  • SQL Server Memory
    SQL Server provides extensive capabilities to cache (store in memory) commonly used information. This includes data that is frequently accessed, together with frequently used SQL statements and their execution plans. Other information is also cached to generally improve performance.

    SQL Server will attempt to use the majority of free memory on the server to improve this caching. It is recommended that more memory is important for an optimal running SQL Server.

  • Client/Server
    SYSPRO provides the ability to configure several different Client/Server arrangements. Each of these can be used depending on the environment, LAN/WAN configuration etc.

    There are 3 parts (tiers) to SYSPRO running on SQL Server. Each of these can be configured to run on a separate computer or may be run in various combinations.
    1 - Client
    2 - Application server
    3 - SQL Server

    For example the Application server and SQL Server can run on the same Windows server. Alternatively, on a notebook system all 3 tiers can run on the same computer.

    Generally the best level of performance will be gained by having the Application server and SQL Server on the fastest available computers.

Note that we have many sites running successfully with a 2-tier environment. This has separate client PC's and the application server and SQL Server running on the same server.

The computer running SQL Server should have the most memory.

SQL Server Tuning

SQL Server is designed to be largely self-tuning - optimizing itself depending on the current computer configuration.

However there are some situations where manual tuning can give the best levels of performance.

Using fixed memory for SQL Server

As SQL Server prefers a large amount of memory for caching it will continually attempt to use/release memory as other applications on the server run or end. This can lead to excessive auto-tuning occurring when many processes are starting and stopping (such as when SYSPRO is configured with SQL Server and the Application Server on the same system). See Details about SQL Server and dynamic memory

We have found that manually setting the amount of memory that SQL Server can use gives substantially better performance. This is true whether running on a live system on a server or a development system on a notebook.

Use the Enterprise Manager and right-click on the Server. There is a Memory tab that can be used to set a Fixed memory size.

Ensure that the log file(s) reside on different hard drive to the databases

Whenever any information is changed in a database a log of the changes is output. Due to the sequential access nature of a log (records are simply added) improved disk seek times can be gained by placing the log file on a different physical disk drive. This is also preferable in the case of a disk crash when the disk containing the database is lost. The log file can then be applied to a previously backed up version of the database to restore the database to the situation immediately preceding the disk crash.

See the SYSPRO Help for suggestions about how to setup SQL Server.

Details about SQL Server and dynamic memory

When SQL Server is using memory dynamically (the default), it queries the system periodically to determine the amount of free physical memory available. SQL Server grows or shrinks the buffer cache to keep free physical memory at a fixed amount.

If there is less than the memory required, SQL Server releases memory to Windows that usually goes on the free list. If there is more than the amount of required physical memory, SQL Server recommits memory to the buffer cache. SQL Server adds memory to the buffer cache only when its workload requires more memory.; a server at rest does not grow its buffer cache.

When the memory is fixed it does not have to periodically query the system to determine the amount of memory required.

Since this article was initially authored the exact details of how SQL Server manages it's memory differ, however the concept is still the same.

How to create a database and log file on different hard drives

The following statement can be used to create a database and its log file on different hard drives. Use the Query Analyzer:

CREATE DATABASE SysproOutdoors

ON PRIMARY (

NAME=SysproOutdoors,

FILENAME=C:\SqlData\SysproOutdoors.mdf,

SIZE=500,

MAXSIZE=700,

FILEGROWTH=10%)

LOG ON (

NAME=SysproOutdoors_log,

FILENAME=D:\SqlLog\SysproOutdoors.ldf,

SIZE=300,

MAXSIZE=500,

FILEGROWTH=10%)

Notes:

  • You could use MAXSIZE=UNLIMITED for unlimited database growth.

  • MAXSIZE and FILEGROWTH only need to be specified if the default automatically grow files option is being used.

  • Remember to create the database before running the SYSPRO C-ISAM to SQL Wizard. You can then use the option I will create the database myself in the wizard.

  • It is recommended that the setting for the database tempdb is also setup in this manner.

General SQL Server notes

  • The master database should be backed up after a user database is created

  • Whilst every effort has been made to ensure that the recommendations provided in this document are correct; it is possible that you may not see the same improvements in performance on all hardware and software configurations.

Optimizing your coding for SQL Server performance

See the topic SQL Server Tuning Code to see what can be done to improve the performance of your code.

See also

SQL Server tuning code, SQL Server User Defined Tables, Transaction Processing, Timestamp, Exclusive Locking, Transferring data between ISAM and SQL, SQL Server Tuning more than 300 columns, SQL-GENERATE-WHERE-LIKE, SQL-SET-FAST-CURSOR, SQL-RESET-FAST-CURSOR, SQL.PRO


SQL Server Tuning Code

Introduction

This topic discusses various techniques that can be used to optimize the performance of SYSPRO programs running on a SQL Server based company. It is aimed at developers using Net Express to write their applications.

If you want to see how to add access your own custom tables see the topic SQL Server User Defined Tables.

It also includes a topic about how to determine the version of SQL Server being used.

Example

In this document we assume the following contents of the Inventory Master and Inventory Warehouse tables.

Table: InvMaster

StockCode | Description | Mass
A | Item A | 32.000000
B | Item B | 15.000000
C | Item C | 1.000000
D | Item D | 100.000000

Table: InvWarehouse

StockCode | Warehouse | QtyOnHand | DateLastSale
A | AA | 1.000 | 2001-06-04
A | BB | 2.000 | 2001-01-01
A | CC | 3.000 | NULL
B | AA | 10.000 | 2000-12-20
B | BB | 20.000 | 1999-04-28
D | AA | 1.500 | 2001-03-16
D | BB | 2.200 | 2001-05-01

Sample coding to process C-ISAM Inventory master and Warehouse files

The following coding is a typical example of reading the Inventory master and Warehouse files. It is assumed that there are fields for a range of stock codes and range of warehouses.

01 FROM-STK PIC X(30). *> From stock code

01 T0-STK PIC X(30). *> To stock code

01 FROM-WH PIC X(2). *> From Warehouse

01 TO-WH PIC X(2). *> To Warehouse

MOVE SPACES TO INVMST-KEY.

MOVE FROM-STK TO INVMST-STK.

PERFORM INVMST-START-GE.

IF STAT-INVALID-KEY

GO TO END-OF-REPORT.

GET-STOCK-NEXT.

PERFORM INVMST-READ-NEXT.

IF STAT-AT-END

GO TO END-OF-REPORT.

PERFORM COMER.

IF INVMST-STK > TO-STK

GO TO END-OF-REPORT.

MOVE SPACES TO INVWHS-KEY.

MOVE INVMST-STK TO INVWHS-STK.

MOVE FROM-WH TO INVWHS-WH.

PERFORM INVWHS-START-GE.

IF STAT-INVALID-KEY

GO TO GET-STOCK-NEXT.

GET-WH-NEXT.

PERFORM INVWHS-READ-NEXT.

IF STAT-AT-END

GO TO GET-STOCK-NEXT.

PERFORM COMER.

IF INVWHS-STK NOT = INVMST-STK

GO TO GET-STOCK-NEXT.

IF INVWHS-WH > TO-WH

GO TO GET-STOCK-NEXT.

PERFORM PROCESS-STOCK-CODE-AND-WAREHOUSE.

GO TO GET-WH-NEXT.

END-OF-REPORT.

PERFORM PROCESS-END-OF-REPORT-TOTALS.

Discussion of above traditional logic

When using a C-ISAM file structure the above logic is typically used, however when processing data stored in a SQL database this has the following issues:

  • A single cursor is used to process the inventory master table

  • A separate cursor is created, fetched and closed on the inventory warehouse table for each stock code

  • The cursor used for processing the inventory master table will start at the initial stock code and continue to the end of the table even though the program will stop the fetches when the To stock code is reached.

  • The cursor used for processing the inventory warehouse table will start at the current stock code and From warehouse and continue to the end of the table even though the program will stop the fetches when the highest warehouse and/or next stock code is fetched. This means that an extra fetch is required to either find the next warehouse or next stock code.

A more efficient process on SQL would be:

  • Generate a logical table JOIN so that each fetch returns both inventory master and warehouse information.

  • Use WHERE logic to select the range of stock codes and warehouses.

An example efficient SQL statement

A sample SQL statement is shown below. This assumes that the From stock code is B and the To stock code is E and the From warehouse is BB and the To warehouse is CC.

SELECT a.StockCode, a.Description, a.Mass, b.Warehouse, b.QtyOnHand, b.DateLastSale

FROM InvMaster a

LEFT JOIN InvWarehouse b ON (a.StockCode = b.StockCode)

WHERE (a.StockCode >= 'B' AND a.StockCode <= 'E')

AND (b.Warehouse >= 'BB' AND b.Warehouse <= 'CC')

ORDER BY a.StockCode, b.Warehouse

Without the WHERE clause this would return the following rows of data

StockCode Description Mass Warehouse QtyOnHand DateLastSale

A Item A 32.000000 AA 1.000 2001-06-04

A Item A 32.000000 BB 2.000 2001-01-01

A Item A 32.000000 CC 3.000 NULL

B Item B 15.000000 AA 10.000 2000-12-20

B Item B 15.000000 BB 20.000 1999-04-28

C Item C 1.000000 NULL NULL NULL

D Item D 100.000000 AA 1.500 2001-03-16

D Item D 100.000000 BB 2.200 2001-04-01

With the WHERE clause the rows returned would be

StockCode Description Mass Warehouse QtyOnHand DateLastSale

B Item B 15.000000 BB 20.000 1999-04-28

D Item D 100.000000 BB 2.200 2001-04-01

By issuing the SQL Server statement shown in this example there will be a dramatic effect on the performance when multiple tables are JOIN'ed or when a small subset of the data is to be returned.

How to implement efficient SQL statements in a SYSPRO program

Instead of embedding SQL commands within the source code of a typical program (especially as these embedded SQL statements may not compile on some platforms) a number of functions have been implemented that can be used to issue SQL statements and return the results in a flexible and effective way.

These functions remove the need for a programmer to understand the intricacies of using the Net Express OpenESQL syntax. However a good understanding of SQL Server and T-SQL are helpful in generating the best SQL Server statements.

The functions are enabled with two copybooks SQL.WRK and SQL.PRO. The various functions in SQL.PRO call a support program called IMPSQF. This handles the actual interaction with SQL Server. Note that this is a native code (.GNT) program for optimum performance and is designed for a Windows environment only.

The process of using these new functions consist of:

  • Including SQL.WRK and SQL.PRO in the source code

  • Setting a flag indicating that the SQL optimization is required

  • Initializing the SQL functions

  • Building the efficient SQL statement including optional joins by
    - Specifying the tables required and the joins between then
    - Specifying the columns required
    - Specifying the include logic required
    - Specifying the sequence required
    - Specifying any optimization flags

  • Fetching the data returned until the end of the result set

  • Shutting down the SQL functions

Each of these will be discussed below. The Software Development Kit contains programs SDKSEL.CBL, SDKSE2.CBL and SDKP25.CBL which demonstrates using an efficient SELECT statement and a program called SDKUPD.CBL that demonstrates efficient UPDATE and DELETE statements.

Setting a flag indicating that the SQL optimization is required

As most program will retain their C-ISAM logic, a flag is needed to indicate whether C-ISAM or SQL logic is to be used. A flag called SQL-FLAG is defined in STANDARD.WRK. Using the following statement will set this flag to Y when the SQL optimization is required/allowed:

PERFORM SQL-FLAG-SETUP.

Note that setting your site id to 'NoOpt' (exact case) will ensure that the flag is never set and can be used to compare the output for testing and the performance without editing and recompiling the source code.

Also note that setting your diagnostic code to 'sql01' (exact case) will cause the program IMPSQF to output a log file of the SQL Server statement being issued. This file will only contain the last SQL Server statement issued. The log file generated is called Base\Settings\ADMIN.SQL - where ADMIN is the operator code being used.

Setting your diagnostic code to 'sql02' (exact case) will cause the program IMPSQF to output a log file of each and every SQL Server statement being issued. This will append each statement issued to the log file. You should remember to remove the file when you have finished. The log file generated is called Base\Settings\ADMIN.SQL - where ADMIN is the operator code being used.

Both of the diagnostic codes sql01 and sql02 are also be used by the Report Writer in a similar manner.

Initialising the SQL functions

When the program starts to process the data required, just before the normal C-ISAM functions, the following coding can be inserted.

IF SQL-FLAG = "Y"

PERFORM SQL-OPT-BUILD-SQL-CMD

GO TO GET-STOCK-NEXT.

Building the SQL command

The following section provides an introduction to the process required to build and issue a SQL command and how to return the result set.

Initialize the command

Before generating a SQL command you must use the SQL-INITIALISE function. Simply add PERFORM SQL-INITIALISE before using any of the other functions and before referencing the other fields mentioned below.

Define the primary table

The primary table name must be moved to SQL-TAB-NAM(1) - this should generally include an alias (typically the alias 'a' is used for the primary table. For example MOVE "a.InvMaster" to SQL-TAB-NAM(1).

Joins

If you need to join another table to the primary table then move the name of the secondary table to SQL-TAB-NAM(x) again with an alias as the initial character (usually b, c etc). You can define up to 20 joined tables in total. If required you can specify an additional 21 tables - for a total of 42 tables in all. See the section headed Accessing more than 21 tables in a single SELECT statement later in this topic.

For each non-primary table you should define the table join using SQL-TAB-LNK(2,1) for the first join (use SQL-TAB-LNK(2,2) for any second part to the join etc). Each of these can be up to 100 characters each.

If you want to define a special join, or need more than 100 characters, then move S to SQL-TAB-MAN(x) and move up to 1000 characters of JOIN information to SQL-TAB-LK(x).

Columns

Then define up to 300 columns of data required to be returned by each fetch. Move the Alias.ColumnName to the fields SQL-COL-NAM(x) - for example 'a.StockCode'. If the column is numeric then move N to SQL-COL-AND(x) and if a date move D to SQL-COL-AND(x) - the default is A for alphanumeric.

In the unlikely case where you need to return more that 300 columns then see the SQL Server tuning more than 300 columns topic.

The maximum length of the 'Column name' supported is 30 characters. All SYSPRO column names are a maximum of 18 characters long.

Conditions

Next you should define any conditions. This defines the WHERE clause of the SELECT statement. If you wish to simply return all rows then you do not need to define the WHERE logic.

To define the WHERE logic there is a 3000 character free-format field called SQL-CON. This can contain any valid SQL Server conditional logic that can appear after the 'WHERE' phrase.

To simplify your coding you can reference up to 30 parameters - defined %1 through %30. You define the values of these parameters by moving them to SQL-PAR-ALP(x), SQL-PAR-NUM(x) and SQL-PAR-DAT(x) where x is the number from 1-30. You should also move in the type (A,N,D) to SQL-PAR-AND(x).

The reason this can simplify the code is that when including an alphanumeric field it must be surrounded in single quotes, and if the alphanumeric string contains single quotes they must be doubled up, numeric fields will be edited in an appropriate format for a WHERE statement and similarly date fields will be edited appropriately. Using a parameter (such as %1) means you do not have to cater for these issues - the system will apply appropriate variable substitution at run-time.

You must not use LOW-VALUES or HIGH-VALUES anywhere in the WHERE statement. See the example below about how to use the parameters.

See the separate section titled Pattern matching below about how best to search for wildcard patterns using a LIKE clause.

Sequencing

Next you should define the sequencing by specifying an ORDER BY clause. The sequence that the columns will be returned is undefined by SQL server unless you specify a specific sequence. Therefore it is highly recommended that you specify an appropriate sequence.

Generally for best performance you should use the primary key columns as the sequence, or when relevant, one of the standard alternate indexes defined against the table. However you can specify any field - regardless of whether the column is indexed or not.

Care should be taken when specifying ORDER BY columns to ensure appropriate level of performance is maintained.

Optimization

Next you can define any additional optimization settings. Currently there are two additional settings they are:

MOVE "Y" TO SQL-WITH-NOLOCK

This indicates that the columns will be returned regardless of any locking. Generally this is the preferred setting when simply printing, searching or viewing data. If this flag is not set and the data is locked SQL Server will loop (appear to hang) until the transaction locking the data has issued a COMMIT or ROLLBACK statement. This guarantees that the data is consistent. Setting this flag to Y can make the statement run faster as the system does not have to test for any locks.

MOVE "Y" TO SQL-NEW-CON

This indicates that a new SQL connection is to be used for the SELECT statement in such a way as to optimize the performance. This can give significant additional performance. It is important that no other SQL statements of any type are issued from the time that the statement is built and issued until the SQL statement is shutdown (using SQL-SHUTDOWN). Be careful when using this flag that the operator cannot access any other function that may possibly issue a SQL command. Setting this flag to Y can have a significant effect on the performance, the SQL statement may run 5-10 times faster or more!

Note that when using this option a new connection will be made for each statements issued. This small overhead should easily be overcome due to the increased performance. However an incorrectly configured system can add up to a 2 second overhead to each connection. Use the SQL Server diagnostic program (IMPDG6) and view the connection speed to ensure that this is not a problem on your system. When you load IMPDG6 and login to SQL Server it will display the current connection time.

Build the command

Next you should use PERFORM SQL-BUILD-COMMAND to build the command and check any basic syntax errors using the PERFORM COMER function. If you have the diagnostic options 'sql01' or 'sql02' the statement is logged at this time. Note that only basic validation is checked at this time - for example you have forgotten to setup a primary table.

Fetch the results

Then you should fetch the result set using PERFORM SQL-FETCH-ROW. This fetches one row at a time. The actual SQL statement is only processed by SQL Server when using the first fetch. SQL Server will reject any invalid syntax at this time. Use of the PERFORM COMER function after each fetch ensures that you will detect any SQL Server syntax errors.

For example if you have spelt a column name or table name incorrectly the PERFORM COMER after the first FETCH will display the SQL Server error message.

It is important to use the PERFORM COMER function after the fetch and to remember to check for a STAT-AT-END condition as this signifies the end of the result set.

Shutdown the current result set

Lastly you must shutdown the SQL command using PERFORM SQL-SHUTDOWN. This will de-allocate any resources used. This is critical when using the SQL-NEW-CON optimization and highly recommended at all times.

Each statement that is issued must use both the SQL-INITIALISE and SQL-SHUTDOWN functions.

Example coding to generate the SQL SELECT statement defined previously follows.

***********************************

** Build Optimized SQL command **

***********************************

SQL-OPT-BUILD-SQL-CMD.

PERFORM SQL-OPT-BUILD-1 THRU SQL-OPT-BUILD-END.

SQL-OPT-BUILD-1.

PERFORM SQL-INITIALISE.

* Define tables to be used, their alias and links

MOVE "a InvMaster " TO SQL-TAB-NAM(1)

MOVE "b InvWarehouse " TO SQL-TAB-NAM(2).

MOVE "a.StockCode = b.StockCode" TO SQL-TAB-LNK(2,1).

*

** Define columns to be used by report

MOVE "a.StockCode " TO SQL-COL-NAM(1).

MOVE "a.Description " TO SQL-COL-NAM(2).

MOVE "a.Mass " TO SQL-COL-NAM(3).

MOVE "N" TO SQL-COL-AND(3).

MOVE "b.Warehouse " TO SQL-COL-NAM(4).

MOVE "b.QtyOnHand " TO SQL-COL-NAM(5).

MOVE "N" TO SQL-COL-AND(5).

MOVE "b.DateLastSale " TO SQL-COL-NAM(6).

MOVE "D" TO SQL-COL-AND(6).

*

** Define conditions to be applied

MOVE SPACES TO SQL-CON.

MOVE 1 TO SQL-CX1.

IF FROM-STK NOT = SPACES AND NOT = ALL "0"

PERFORM SQL-CON-NEXT

MOVE "a.StockCode >= %1 AND" TO SQL-CON(SQL-CX1:).

IF TO-STK NOT = HIGH-VALUES AND NOT = ALL "9"

PERFORM SQL-CON-NEXT

MOVE "a.StockCode <= %2 AND" TO SQL-CON(SQL-CX1:).

IF FROM-WH NOT = SPACES

PERFORM SQL-CON-NEXT

MOVE "b.Warehouse >= %3 AND" TO SQL-CON(SQL-CX1:).

IF TO-WH NOT = HIGH-VALUES

PERFORM SQL-CON-NEXT

MOVE "b.Warehouse <= %4 AND" TO SQL-CON(SQL-CX1:).

PERFORM SQL-CON-END. *> Remove last AND (if any)

*

** Define variables

MOVE FROM-STK TO SQL-PAR-ALP(1).

MOVE TO-STK TO SQL-PAR-ALP(2).

MOVE FROM-WH TO SQL-PAR-ALP(3).

MOVE TO-WH TO SQL-PAR-ALP(4).

*

** Define sequence

MOVE "a.StockCode " TO SQL-SEQ-COL(1).

MOVE "b.Warehouse " TO SQL-SEQ-COL(2).

*

** Additional SQL optimization settings

MOVE "Y" TO SQL-WITH-NOLOCK.

MOVE "Y" TO SQL-NEW-CON.

*

** Now build the SQL command

PERFORM SQL-BUILD-COMMAND.

PERFORM COMER.

SQL-OPT-BUILD-END.

Fetching the result set

Next you will need to fetch the results of the SELECT statement. This is done using the PERFORM SQL-FETCH-ROW function. This function updates STAT-CODE in a similar way to the normal C-ISAM READ NEXT function, therefore you can use STAT-AT-END to detect the end of the result set. To ensure that other SQL errors are detected you must also use PERFORM COMER.

When a valid set of data is returned the program will generally move the results back into the C-ISAM record layout allowing normal program functions to resume. This is of course up to you how you code your application.

See the following example

****************************************

** Fetch next row and return values **

****************************************

SQL-FETCH-NEXT-ROW.

PERFORM SQL-FETCH-NEXT-1 THRU SQL-FETCH-NEXT-END.

SQL-FETCH-NEXT-1.

PERFORM SQL-FETCH-ROW.

IF STAT-AT-END

GO TO SQL-FETCH-NEXT-END.

PERFORM COMER.

*

** Extract column values and move back to record area

PERFORM INVMST-INITIALIZE-REC.

PERFORM INVWHS-INITIALIZE-REC.

MOVE SQL-COL-ALP(1) TO INVMST-STK. *> a.StockCode

MOVE SQL-COL-ALP(2) TO INVMST-DESC. *> a.Description

MOVE SQL-COL-NUM(3) TO INVMST-MASS. *> a.Mass

MOVE SQL-COL-ALP(4) TO INVWHS-WH. *> b.Warehouse

MOVE SQL-COL-NUM(5) TO INVWHS-NHD. *> b.QtyOnHand

MOVE SQL-COL-DAT(6) TO INVWHS-SALDAT. *> b.DateLastSale

SQL-FETCH-NEXT-END.

Special notes on the fetch function

The SQL statement built using SQL-BUILD-COMMAND is executed when the first SQL-FETCH-ROW function is performed. Any invalid SQL syntax, invalid table names, invalid column names, invalid WHERE syntax etc will be detected at this time. It is important that the PERFORM COMER is placed after the SQL-FETCH-ROW to detect and display any error messages.

When fetching alphanumeric values the first 100 character are returned in SQL-COL-ALP(x). If the column contains more than 100 characters then you must use the SQL-GET-VAL function. See the following example:

MOVE "a.Description" TO SQL-COL-1. *> Column name

PERFORM SQL-GET-VAL.

MOVE SQL-ALP-1 TO CHR255. *> Returns up to 255 chars

Terminating the SQL statement

It is important to terminate the SQL statement to return any resources used by the command. This is even more important if you have moved Y to the SQL-NEW-CON field. To terminate the command simply use:

PERFORM SQL-SHUTDOWN.

Remember to place this at ENDJOB in case the program fails with a COMER error.

Error messages

After each SQL function you should use PERFORM COMER. This will detect and display any error messages. Click on the Extended SQL Information button when the error message SQL-022 Invalid SQL command See Extended SQL Information is shown. There are two types of error messages generated and displayed when using the SQL functions:

  • If a problem is detected by the SYSPRO functions the error message starts with [SYSPRO]

  • Once the fetch is being executed SQL Server may return error messages. These typically start with [Microsoft][ODBC SQL Server Driver]

If you cannot immediately see the problem with the SQL statement you can copy and paste the command to the Query Analyzer and run it there.

Verifying the SQL command being generated

You can view the SQL command being generated by setting the diagnostic code of your system to sql01 (note this must be lowercase). When the command is generated a text file called base\settings\{oper}.sql will be created where {oper} is your operator code. This can be opened using the Query Analyzer and the script can be run using the F5 Run function. Set you diagnostic code to sql02 to cause this file to be accumulated.

You should only set the diagnostic code to these values when debugging your application.

Comparing Optimized and non-Optimized performance

The PERFORM SQL-FLAG-SETUP function has a special check that if your site id is NoOpt (case sensitive) that the SQL-FLAG will never be set. Thus by setting your site id to NoOpt you can disable any SQL optimization.

Remember to clear this setting when you have finished as it will negatively affect system performance.

Additional notes on using parameters

When defining the WHERE parameters %1 through %30 you must insert a space or opening/closing brackets '(' or ')' after the parameter for the automatic replacement to take place.

Do not use LOW-VALUES or HIGH-VALUES as a parameter value - rather generate a different condition.

Searching using wildcards

To search an alphanumeric field using a wildcard requires use of the LIKE phrase. The wildcards used in this phrase are different from those normally used in other applications such as the '*' and '?'.

In addition most SYSPRO databases are case sensitive and WHERE conditions are case sensitive therefore for you to issue a case insensitive search using wildcards requires a little more code. You must specify each character as being upper or lower case where each character is surrounded by an open and close square bracket. For example searching for 'a' requires you to specify '[Aa]'.

See the function SQL-GENERATE-WHERE-LIKE which is designed to assist you in generating the most common LIKE phrases.

For example passing this function the string '*John*' returns '%[Jj][Oo][Hh][Nn]%'. The output of this function can be passed to the SQL-CON field when defining an optimized command or can be passed in one of the parameter fields mentioned above - be careful about the length of the field when using a parameter.

Alternative JOINs available

The default JOIN used when linking tables is the LEFT JOIN. This means that for each row on the left hand side of the link zero, one or more rows will be included from the right side of the link that match the condition specified. This is typically the required JOIN.

However when each secondary table is specified you can include the JOIN type in the field SQL-TAB-MAN(x). The options available are:

SQL-TAB-MAN flag | Join type
Spaces | LEFT JOIN
R | RIGHT JOIN
F | FULL JOIN
I | INNER JOIN

Accessing more than 21 tables in a single SELECT statement

The copybook SQL.WRK allows you to define a single (primary) table and an additional 20 (secondary) tables that can be accessed in a single SELECT statement. This means that you can easily create a SELECT statement that references up to 21 tables in total.

Prior to SYSPRO 6.1 this limit was one primary and 10 additional tables (for a total of 11 tables in all).

However, even though we now allow a total of 21 tables to easily be specified in a single command we have additionally allowed you to access an additional 21 tables (for a total of 42 tables).

See the following description for how this can be done.

Assume that you have up to 42 tables to be accessed in a single SELECT statement.

After the PERFORM SQL-INITIALISE statement move in tables 22-42 into the columns SQL-TAB-NAM(x) where x is a value from 1-21. For example move your table number 22 to the field SQL-TAB-NAM(1) and your table number 23 to the field SQL-TAB-NAM(2) up to table number 42 to the field SQL-TAB-NAM(21).

Leave the table names blank when you have finished defining your list of tables from 22 upwards. i.e. as soon as the SQL code detects a blank table name it assumes that this is the end of the list of tables to be included.

Then perform SQL-DEFINE-EXTRA-TABLES. This causes the SQL Server optimized logic to store the table definitions from 22 upwards.

Then you should immediately define your tables 1-21 in the fields SQL-TAB-NAM(x) as normal. You must define all 21 tables with no gaps. Rememer that as soon as it finds a blank table name it assumes that this is the end of the list of tables to be included.

Continue to define and build the SQL statement as normal using PERFORM SQL-BUILD-COMMAND and fetch the result set using SQL-FETCH-ROW.

See the following code fragments:

perform sql-initialise.

*

** As we have more than 21 tables we must first add extra

** table definitions (this will be table number 22 upwards)

*

** Anniversary date

move "v CrmDate " to sql-tab-nam(1).

move "a.ContactId = v.ContactId" to sql-tab-lnk(1,1).

move "v.DateType = 2" to sql-tab-lnk(1,2).

perform sql-define-extra-tables.

*

*

*

** Now define 21 regular table definitions

move "a CrmContact " to sql-tab-nam(1).

*

** Accounts

move "b CrmOrganization " to sql-tab-nam(2).

move "a.ContactId = b.ContactId" to sql-tab-lnk(2,1).

move "b.OrganizationType = 'A'" to sql-tab-lnk(2,2).

*

** Now continue defining file definitions up to 21...

** I have left out this code in this example.

*

** Define columns to be used

move 1 to x1.

*

move "a.ContactId " to sql-col-nam(x1). add 1 to x1.

move "a.FullName " to sql-col-nam(x1). add 1 to x1.

move "a.Title " to sql-col-nam(x1). add 1 to x1.

*

** Anniversary date (note use of column from table 22)

move "D" to sql-col-and(x1).

move "v.ContactDate " to sql-col-nam(x1). add 1 to x1.

The rest of the code is exactly the same as if we were just using up to 21 tables.

Defining 2 character table aliases

The above mentioned logic that allows you to configure up to 42 tables in a single SELECT typically uses a single character alias (a-z) to reference each table.

However the fields that describe each table/column in SQL.WRK only allow you to assign a single character alias. This limits the number of tables to 26 (a-z).

The following describes how you can use 2 character aliases to access up to 42 tables.

The primary table must use a single character alias - it is recommended to use 'a'.

When describing your sub-tables (the ones joined to one or more other tables) just specify the two character alias follows by a dot ('.') followed by the table name. Similarly when defining a column name you must also prefix the column name with the 2 character alias and a dot ('.').

It is recommended that you limit your two character aliases to consisting of the characters a-z and 0-9.

See the following example:

perform sql-initialise.

*

** Define the primary table (use 'a' as the alias)

move "a.InvMaster" to sql-tab-nam(1).

*

** Define a joined table with a 2 character alias

move "b1.InvWarehouse" to sql-tab-nam(2).

move "S" to sql-tab-man(2).

move "a.StockCode = b1.StockCode" to sql-tab-lk(2).

*

** Define columns to be used

move 1 to x1.

*

move "a.StockCode " to sql-col-nam(x1). add 1 to x1.

move "a.Description " to sql-col-nam(x1). add 1 to x1.

*

** Note use of 2 character alias

move "b1.Warehouse " to sql-col-nam(x1). add 1 to x1.

move "N" to sql-col-and(x1).

move "b1.QtyOnHand " to sql-col-nam(x1). add 1 to x1.

*

** Define sequence

move "a.StockCode " to sql-seq-col(1).

move "b1.Warehouse " to sql-seq-col(2).

*

** Additional SQL optimization settings

move "Y" to sql-with-nolock.

move "Y" to sql-new-con.

*

** Now build the SQL command

perform sql-build-command.

perform comer.

Important - the code to support 2 character aliases was available from SYSPRO 6.1 port 28 onwards.

Updating and Deleting information using SQL statements

In addition to reading data using an efficient SELECT statement there are SYSPRO functions to allow you to update and delete data. These are described below.

SQL UPDATE

When updating data there are two issues which make the new function faster than using an C-ISAM REWRITE statement.

  • You can select to update selected columns, rather than every column in the table

  • You can use a WHERE statement to update more than a single row with a single UPDATE statement

This is particularly useful for batch update type functions.

For example to set the Inventory Master column called LowLevelCode to zero for all stock codes you can use the following SQL statement.

UPDATE InvMaster

SET LowLevelCode = 0

This can be done using the following coding.

**************************************************************

** Routine to issue SQL UPDATE statement **

** UPDATE InvMaster SET LowLevelCode = 0 **

**************************************************************

UPDATE-FUNCTION.

PERFORM UPD-1 THRU UPD-END.

UPD-1.

PERFORM SQL-INITIALISE.

*

** Define table to be used

MOVE "InvMaster " TO SQL-TAB-TAB(1)

*

** Define columns to be updated

MOVE "LowLevelCode " TO SQL-COL-COL(1).

MOVE ZERO TO SQL-COL-NUM(1).

MOVE "N" TO SQL-COL-AND(1).

*

** Define conditions to be applied

MOVE SPACES TO SQL-CON.

*

** Now build and issue the SQL UPDATE command

PERFORM SQL-UPDATE-ROWS.

PERFORM COMER.

UPD-END.

Additional notes on SQL-UPDATE-ROWS function

Alternatively rather than a fixed string, decimal value or date you may wish to update the contents of one column by the contents of another. For example say you want to move the value of the Description column to the LongDesc column when the LongDesc column is spaces you could use the following routine.

**************************************************************

** Routine to issue SQL UPDATE statement **

** UPDATE InvMaster SET LongDesc = Description **

** WHERE LongDesc = ' ' **

**************************************************************

UPDATE-FUNCTION.

PERFORM UPD-1 THRU UPD-END.

UPD-1.

PERFORM SQL-INITIALISE.

*

** Define table to be used

MOVE "InvMaster " TO SQL-TAB-TAB(1)

*

** Define columns to be updated

MOVE "LongDesc " TO SQL-COL-COL(1).

MOVE "Description " TO SQL-COL-ALP(1).

MOVE "C" TO SQL-COL-AND(1). *> Column name!

*

** Define conditions to be applied

MOVE "LongDesc = ' '" TO SQL-CON.

*

** Now build and issue the SQL UPDATE command

PERFORM SQL-UPDATE-ROWS.

PERFORM COMER.

PERFORM SQL-SHUTDOWN.

UPD-END.

SQL DELETE

The advantage of using the delete function is that you can delete many rows with a single command.

The following example shows deleting all stock codes between 'B' and 'C' (inclusive)

DELETE InvMaster

WHERE StockCode >= 'B' and StockCode <= 'C'

This can be done using the following coding.

**************************************************************

** Routine to issue SQL DELETE statement **

** DELETE InvMaster **

** WHERE StockCode >= 'B' AND StockCode <= 'C' **

**************************************************************

DELETE-FUNCTION.

PERFORM DEL-1 THRU DEL-END.

DEL-1.

PERFORM SQL-INITIALISE.

*

** Define table to be used

MOVE "InvMaster " TO SQL-TAB-TAB(1)

*

** Define conditions to be applied

MOVE "StockCode >= %1 AND StockCode <= %2" TO SQL-CON.

*

** Define variables

MOVE "B" TO SQL-PAR-ALP(1).

MOVE "C" TO SQL-PAR-ALP(2).

*

** Now build and issue the SQL DELETE command

PERFORM SQL-DELETE-ROWS.

PERFORM COMER.

PERFORM SQL-SHUTDOWN.

DEL-END.

General notes on building SQL statements

For best results take note of the following recommendations

  • Use single quotes (') around strings rather that double quotes (")

  • When using quotes to surround a string ensure that the string does not contain single quotes. If it does you must 'double-up' on the quotes. Use parameters (%1 through %30) in the condition so that this will be done for you.

  • Use uppercase for SQL reserved words, such as SELECT, UPDATE, WHERE, FROM

  • Use mixed case (exact case) for column names and table names.

  • Use lowercase letters for table aliases (a, b, c etc).

Pattern matching

If you require to allow the operator to enter a pattern you can use the LIKE statement. For example to find all stock codes with a description beginning 'Item' you could use

SELECT StockCode, Description

FROM InvMaster

WHERE Description LIKE 'Item%'

Special characters in pattern matching

  • Use % to represent the normal * in pattern matching

  • Use _ to represent the normal ? in pattern matching

  • Surround a list of characters by [ and ] to match a single character

Therefore to ensure the comparison is not case-sensitive use

SELECT StockCode, Description

FROM InvMaster

WHERE Description LIKE '[Ii][Tt][Ee][Mm]%'

See the function SQL-GENERATE-WHERE-LIKE - this is designed to assist you in generating the most common LIKE phrases as described above.

For example passing this function the string 'Item*' returns '[Ii][Tt][Ee][Me]%'. The output of this function can be passed to the SQL-CON field when defining an optimized command.

Counting rows in a table

Occasionally you may want to count how many rows exist in a table. This can be done extremely quickly in SQL Server. There is a special function to make this simple.

This can be done with the following sample source code:

MOVE "InvMaster" TO SQL-TAB-TAB(1).

PERFORM SQL-COUNT-ROWS.

MOVE SQL-ROWS TO NUMBER-OF-ROWS.

Verifying whether a table or column exists

One of the issues with using SQL Server is that over time you may wish to change the database structure, often adding new tables or columns to an existing table.

Whilst the user using SYSPRO usually does not have permission to add tables or columns you can still determine whether the required table or column exists. You could then warn the user that the administrator must upgrade the database.

See the following examples:

* Check if InvMaster exists

MOVE "InvMaster" TO SQL-TAB-TAB(1).

PERFORM SQL-CHECK-TABLE-EXISTS.

IF STAT-OK

MOVE "Table InvMaster exists" to xxxxx.

* Check if InvMaster..StockCode exists

MOVE "InvMaster" TO SQL-TAB-TAB(1).

MOVE "StockCode" TO SQL-COL-COL(1).

PERFORM SQL-CHECK-COLUMN-EXISTS.

IF STAT-OK

MOVE "Table InvMaster..StockCode exists" to xxxxx.

Transferring data from ISAM to SQL and back again

There are some cases where business logic requires a large data processing load. It is possible that the performance of the business function is much slower in a SQL Server environment. In these cases you can transfer the data from a SQL Server table to a C-ISAM file and then process the C-ISAM file.

If required any resultant changes can then be transferred back to the SQL Server table.

A utility program (IMPSQM) has been developed to assist developers in transferring data between ISAM and SQL Server. This utility provides a number of functions required for the transfer process.

As part of the Software Development Kit a test harness called SDKSQM has been developed that provides a user-interface to the functions described in this topic. This is useful for a developer or tester to use the functions without having to develop a program to call IMPSQM. In addition as the source code of this test harness forms part of the Software Development Kit you can animate the program to see exactly how this function is used.

Note that SQL Server tables support a virtually unlimited number of rows, whereas there is a maximum file size on C-ISAM files. This should be considered before using this technique.

For more details about this utility see the topic Transferring data between ISAM and SQL.

Other SQL Server functions

These are additional functions that can be useful when optimizing your code for SQL Server environments.

SQL-GET-COLLATION

This function can be used to retrieve the SQL Server collation name for the current SYSPRO database. See the topic SQL Server Creating Temporary Tables for a practical example of how this function can be used.

SQL-EXPAND-PARAMETERS

This function can be used when you wish to execute your own SQL Server command using SQL-EXECUTE-COMMAND but require to include a WHERE string that contains parameters. You can build up a parameterized string with a list of the values for each parameter and then PERFORM SQL-EXPAND-PARAMETERS. This will return a string with the appropriate parameters replaced. This function handles alphanumeric, numeric and data parameters, all of which require special processing for specific values.

SQL-EXPAND-TABLES

This function allows you to pass a list of tables (and company id's for each table if required). After being invoked the function returns a Database..Tablename definition for each table. if the table does not reside in the current SYSPRO database then the Database prefix is built - if the table resides in the current database then no prefix is added and just the original table name is returned. This is particularly useful for tables that use the shared inventory or shared general ledger id's.

SQL-EXECUTE-COMMAND

This function allows you issue any arbitrary SQL Server statement. It is typically useful for maintaining a database (e.g. adding a table, column, index, view etc.) or issuing set based changes. These could include:

- Deleting multiple rows based on complex criteria

- Creating temporary tables, columns and indexes - and populating them

- Set based updates to one or more columns based on complex criteria or using complex computations

- Dropping tables, columns, indexes or other objects with appropriate permission

- Virtually any other command as long as you do not require to retrieve any results

You cannot retrieve any results of this statement. However you could get round this by writing any results to a temporary table and retrieving them separately.

When using SQL-EXECUTE-COMMAND it assumes by default that the field SQL-CON contains the statement to be issued. This requires any parameters to be correctly formatted, table names to be correct referenced (watch out for shared inventory and shared GL tables). The field SQL-CON is 3000 characters in length.

Note that from SYSPRO 6.1 you can pass up to 15,000 characters to this function as follows:

- Move the first 3000 characters to SQL-CON and perform SQL-CMD-EXE-BUILD-1.

- This clears a 15,000 character field and sets up the first 3000 characters.

- Move the next 3000 characters to SQL-CON and perform SQL-CMD-EXE-BUILD-2.

- This stores the next 3000 characters into the 15,000 character string.

- Repeat as required up to SQL-CMD-EXE-BUILD-5.

- Finally perform SQL-EXECUTE-COMMAND as normal.

- This recognizes that you have built a larger string and uses that rather that the regular SQL-CON string.

Determining the version of SQL Server

The current version of SQL Server being used is available to developers in the linkage field LINK-SQL-VRS. This field is populated when you login to SYSPRO and is therefore available to all SYSPRO programs.

This field can be used when you have specific SQL code that is only supported on specific versions or services packs of SQL Server. The field definition has been shown below. Note that the comments show some of the most common versions and service packs.

05 LINK-SQL-VRS.

07 LINK-SQL-VRS-MAJ PIC 9(2).

07 LINK-SQL-VRS-DT1 PIC X.

07 LINK-SQL-VRS-MID PIC 9(2).

07 LINK-SQL-VRS-DT2 PIC X.

07 LINK-SQL-VRS-MIN PIC 9(4).

* SQL Server full version

* For example

* '07.00.0699' - SQL 7.0 SP1

* '07.00.0842' - SQL 7.0 SP2

* '07.00.0961' - SQL 7.0 SP3

* '07.00.1063' - SQL 7.0 SP4

* '08.00.0194' - SQL 2000 RTM

* '08.00.0384' - SQL 2000 SP1

* '08.00.0534' - SQL 2000 SP2

* '08.00.0760' - SQL 2000 SP3

* '08.00.2039' - SQL 2000 SP4

* '09.00.1399' - SQL 2005 RTM

* '09.00.2047' - SQL 2005 SP1

* '09.00.3042' - SQL 2005 SP2

* '09.00.4035' - SQL 2005 SP3

* '10.00.1600' - SQL 2008 RTM

* '10.00.2531' - SQL 2008 SP1

See also

SQL Server tuning, SQL Server User Defined Tables, Transaction Processing, Transferring data between ISAM and SQL, SQL Server tuning more than 200 columns, SQL-GENERATE-WHERE-LIKE, SQL-SET-FAST-CURSOR, SQL-RESET-FAST-CURSOR, SQL.PRO


SQL Server Tuning more than 200 columns

SYSPRO SDK

SQL Server

SQL Server Tuning - Returning more than 300 columns

Introduction

The code you can use to tune programs specifically for SQL Server using SQL.WRK and SQL.PRO is limited to returning 300 columns.

Note that this limit was 200 columns prior to SYSPRO 6.1 which was a more limiting factor. As the limit has been increased to 300 columns from SYSPRO 6.1 onwards it is less likely that you may require the information in this topic.

In the unlikely event of you requiring to return more that 300 columns you can:

  • Define up to 299 columns as normal (or less if required)

  • Define the 300th column as a complex column using a concatenate function

  • Use reference modification to extract each column value from the result

Sample code

The following example reads the StockCode, Description and Mass from the InvMaster table and also concatenates the StockUom and ListPriceCode columns into a single returned column.

See the following code to demonstrate this logic.

***********************************

** Build optimized SQL command **

***********************************

SQL-OPT-BUILD-SQL-CMD.

PERFORM SQL-OPT-BUILD-1 THRU SQL-OPT-BUILD-END.

SQL-OPT-BUILD-1.

PERFORM SQL-INITIALISE.

*

** Build and store complex column with concatenated columns

MOVE "a.StockUom + a.ListPriceCode" TO SQL-CON.

PERFORM SQL-COMPLEX-COLUMN.

*

* Define tables to be used, their alias and links

MOVE "a InvMaster " TO SQL-TAB-NAM(1)

** Define columns to be used by report

MOVE "a.StockCode " TO SQL-COL-NAM(1).

MOVE "a.Description " TO SQL-COL-NAM(2).

MOVE "a.Mass " TO SQL-COL-NAM(3).

MOVE "N" TO SQL-COL-AND(3).

MOVE "{complex} " TO SQL-COL-NAM(4). *> Indicate 'special' column

MOVE "A" TO SQL-COL-AND(4). *> Alphanumeric column

*

** Define conditions to be applied

MOVE SPACES TO SQL-CON.

MOVE 1 TO SQL-CX1.

PERFORM SQL-CON-END. *> Remove last AND (if any)

*

** Define variables

*

** Define sequence

MOVE "a.StockCode " TO SQL-SEQ-COL(1).

*

** Additional SQL optimization settings

MOVE "Y" TO SQL-WITH-NOLOCK.

MOVE "Y" TO SQL-NEW-CON.

*

** Now build the SQL command

PERFORM SQL-BUILD-COMMAND.

PERFORM COMER.

SQL-OPT-BUILD-END.

*

*

****************************************

** Fetch next row and return values **

****************************************

SQL-FETCH-NEXT-ROW.

PERFORM SQL-FETCH-NEXT-1 THRU SQL-FETCH-NEXT-END.

SQL-FETCH-NEXT-1.

PERFORM SQL-FETCH-ROW.

IF STAT-AT-END

GO TO SQL-FETCH-NEXT-END.

PERFORM COMER.

*

** Extract column values and move back to record area

PERFORM INVST-INITIALIZE-REC.

MOVE SQL-COL-ALP(1) TO INVMST-STK. *> a.StockCode

MOVE SQL-COL-ALP(2) TO INVMST-DESC. *> a.Description

MOVE SQL-COL-NUM(3) TO INVMST-MASS. *> a.Mass

MOVE SQL-COL-ALP(4)(1:3) TO INVMST-UM *> a.StockUom

MOVE SQL-COL-ALP(4)(4:2) TO INVMST-LIST. *> a.ListPriceCode

SQL-FETCH-NEXT-END.

See also

SQL Server tuning code, Transaction Processing, Transferring data between ISAM and SQL, SQL.PRO


SQL Server Creating Temporary Tables

Introduction

This topic discusses how to create temporary tables and how to ensure that the collation of character data is correct. See the function BUILD-TEMP-TABLE-NAME.

Creating temporary tables in tempdb

When creating temporary tables using SYSPRO we typically use the BUILD-TEMP-TABLE-NAME function. This generates a table name of the form #Syspro_T0001001 which is guaranteed to be unique across SYSPRO companies running on the same working folder.

The '#' at the beginning of the table name indicates to SQL Server that the table should be created in the system database tempdb. When an application disconnects from SQL Server any tables created in tempdb by that application will be automatically removed.

Collation in tempdb

It is important to realize that tables created in tempdb will use the collation defined when SQL Server was installed. In some cases this may be different from a table used for SYSPRO. This will become a problem if you subsequently attempt to JOIN tables based on character columns where the collations differ.

Note that this is only a problem if the collations differ and a JOIN is implemented on character columns. This may not be found during testing, but an end-user may have differing collations from database to database.

How to resolve collation conflicts

When you create columns in tempdb it is best practise to specify the collation against all character columns.

The sample code included below shows how the existing SYSPRO collation is identified by selecting a standard SYSPRO column and then when a table is generated in tempdb the syntax used to define the 'char' column definition. Note that numeric and date columns do not have this problem.

01 JOB-COLLATION PIC X(40).

* Field used to save collation

* Use the standard function to get the current collation

PERFORM SQL-INITIALISE.

PERFORM SQL-GET-COLLATION.

MOVE SQL-COLLATION TO JOB-COLLATION. *> defined in working-storage

PERFORM SQL-SHUTDOWN.

*

* Build temporary SQL table name...

* NOTE the field sizes are much larger than those on the allocation

* file. This is so that the overflows can be controlled on the temp

* table...

PERFORM BUILD-TEMP-TABLE-NAME.

MOVE TMPFIL TO LAB-TEMP-TABLE. *> defined in working-storage

*

* Note the collation information defined against the job column...

MOVE SPACES TO SQL-CON.

PERFORM SQL-INITIALISE.

STRING

"CREATE TABLE " DELIMITED BY SIZE

LAB-TEMP-TABLE DELIMITED BY SPACE

" (" DELIMITED BY SIZE

"Job char(8) COLLATE " DELIMITED BY SIZE

JOB-COLLATION DELIMITED BY SIZE

" NOT NULL, " DELIMITED BY SIZE

"Operation decimal(4,0) NOT NULL, " DELIMITED BY SIZE

"StartUpIssued decimal(14,2) NULL, " DELIMITED BY SIZE

"SetUpIssued decimal(14,2) NULL, " DELIMITED BY SIZE

"RunTimeIssued decimal(14,2) NULL, " DELIMITED BY SIZE

"ShutdownIssued decimal(14,2) NULL, " DELIMITED BY SIZE

"ValueIssued decimal(14,2) NULL, " DELIMITED BY SIZE

"CONSTRAINT LabKey PRIMARY KEY CLUSTERED " DELIMITED BY SIZE

"(Job, Operation))" DELIMITED BY SIZE

INTO SQL-CON.

PERFORM SQL-EXECUTE-COMMAND.

PERFORM COMER.

PERFORM SQL-SHUTDOWN.

Once the above coding has been executed the table defined in LAB-TEMP-TABLE can be referenced just as if it was a standard SYSPRO table, including JOIN's to standard SYSPRO tables.

For more information about SQL Server collation read the SQL Server Online Books.

See the following topic for more information about SQL Server Tuning code in SYSPRO

See also

SQL Server Tuning, SQL Server Tuning Code, Transaction Processing, Transferring data between ISAM and SQL, BUILD-TEMP-TABLE-NAME, Temporary Files


SQL Server FAQ

What affects the performance of SYSPRO on SQL Server?

There are a large number of factors that affect the performance of SYSPRO running with Microsoft SQL Server.

These include:

  • Windows server configuration

  • Client PC configuration

  • Network configuration

  • SQL Server configuration

  • SYSPRO file handler design

  • SYSPRO application logic

Why does my SYSPRO system on SQL Server run slower than Encore 4.0 (or other ISAM based versions)?

Encore 4.0 was designed to use C-ISAM files. These C-ISAM files are very efficient when it comes to data storage and retrieval.

The disadvantage of C-ISAM files is that they do not provide the necessary levels of data integrity required for enterprise systems. If the server crashes, network problems occur or client PC fails the data can be left in an incomplete state. For example if the application is adding a Debit to one G/L account and then a Credit to another the system could fail between these two parts of the transaction. This would mean that the General Ledger is out of balance. Typically Encore 4.0 provided a Balancing utility that will find and resolve these types of problems. On a system where many problems occur this can lead to excessive system maintenance and in the worst case loss of data may occur.

SYSPRO running on Microsoft SQL Server is designed for rock solid data integrity. This is achieved using Transaction Processing. Transaction Processing is the ability for an application to define a logical business function. This is easiest explained with a simple example.

If the General Ledger system requires that both a Debit and Credit must be posted, then this may be defined as a transaction. The COMMIT/ROLLBACK logic included in SYSPRO programs will ensure that both the debit and credit part-transactions are applied or in the case of any problem (including system failure) that neither of these are applied to the database.

By utilising Transaction Processing this reduces system maintenance requirements.

The ability of the database to guarantee data integrity comes at a cost. This cost is performance. Whilst SYSPRO has been designed to give the best levels of performance, using a database can mean that it runs slower than a purely C-ISAM system.

However a properly tuned SQL Server based system can provide as good as, if not better, performance that an ISAM system. In addition SQL Server tables are not limited by size and provide excellent scalability.

See the information about tuning SYSPRO and SQL Server.

What versions of Windows should I use?

Whilst a comparison of versions of Windows is not in the scope of this document it is clear that specific versions of SQL Server run more effectively on specific versions of Windows. For example in the past SQL Server 2000 running on Windows 2000 runs quicker that SQL Server 7.0 on Windows NT. In some cases the difference is substantial. We recommend that a test bed is used to verify the performance.

Since this article has been authored subsequent versions of both Windows server platforms and SQL Server have been released. It is suggested that you consider later versions as they often improve performance and add significant functionality and security improvements.

What version of SQL Server should I be using?

We do not recommend that you use SQL Server 7.0 as subsequent versions have significant performance and other benefits. In some service packs available with SQL Server 2000 have also provided some performance issue.

See the Support Zone for supported version of SQL Server and Windows server platforms.

Can I or should I add indexes?

When you install SYSPRO on SQL Server the SQL Server Setup wizard will add all the standard indexes required by standard SYSPRO programs.

The vast majority of SYSPRO programs use these standard indexes so you should get the best level of performance.

However we have noticed that a number of end-users have migrated their data (often using the DTS wizard) and they have not elected to retain their indexes. This has a dramatic negative effect on the system overall performance.

To resolve the cases where the standard indexes have been lost there is a process that can be used to rebuild these missing indexes. See the Support Zone for help on this process.

Lastly whilst end-users may add indexes to the standard SYSPRO tables please note the following:

  • Adding indexes slows general SYSPRO processing, especially posting and maintenance programs when the database has to maintain your new indexes

  • It is recommended to prefix the index names with Usr_ to avoid possible conflict with any future key SYSPRO may add.

  • It is recommended to create a script that can be run to add your indexes. In this way you can ensure that the indexes are rebuilt after a new software version has been installed.

  • SYSPRO may have a problem when installing new software versions if your indexes cause duplicates or other unexpected issues. It is recommended to remove your indexes before upgrading to a later SYSPRO release. This is generally only important when migrating to a new release, issue or service pack of SYSPRO.

Where can I find more information?

For more FAQ's see the SYSPRO Help related to SQL Server.

In addition the latest information is posted to the SQL section of the Support Zone at www.syspro.com

See also

SQL Server tuning, Transaction Processing, Transferring data between ISAM and SQL


Transaction Processing

SYSPRO SDK

SQL Server

Transaction Processing in SYSPRO

Introduction

This document contains an overview of Transaction Processing and detailed explanations of how this is utilized in SYSPRO.

Overview of Transaction Processing

The following explains what is meant by a transaction.

A transaction is a sequence of operations performed as a single logical unit of work. A logical unit of work must exhibit four properties, called the ACID (Atomicity, Consistency, Isolation, and Durability) properties, to qualify as a transaction:

Atomicity

A transaction must be an atomic unit of work; either all of its data modifications are performed, or none of them is performed

Consistency

When completed, a transaction must leave all data in a consistent state. In a relational database, all rules must be applied to the transaction’s modifications to maintain all data integrity. All internal data structures, such as B-tree indexes or doubly linked lists, must be correct at the end of the transaction

Isolation

Modifications made by concurrent transactions must be isolated from the modifications made by any other concurrent transactions. A transaction either sees data in the state it was in before another concurrent transaction modified it, or it sees the data after the second transaction has completed, but it does not see an intermediate state. This is referred to as serializability because it results in the ability to reload the starting data and replay a series of transactions to end up with the data in the same state it was in after the original transactions were performed

Durability

After a transaction has completed, its effects are permanently in place in the system. The modifications persist even in the event of a system failure.

Specifying and Enforcing Transactions

SQL programmers are responsible for starting and ending transactions at points that enforce the logical consistency of the data. The programmer must define the sequence of data modifications that leave the data in a consistent state relative to the organization’s business rules. The programmer then includes these modification statements in a single transaction so that Microsoft® SQL Server™ can enforce the physical integrity of the transaction.

It is the responsibility of an enterprise database system, such as SQL Server, to provide mechanisms ensuring the physical integrity of each transaction. SQL Server provides:

  • Locking facilities that preserve transaction isolation.

  • Logging facilities that ensure transaction durability. Even if the server hardware, operating system, or SQL Server itself fails, SQL Server uses the transaction logs, upon restart, to automatically roll back any uncompleted transactions to the point of the system failure.

  • Transaction management features that enforce transaction atomicity and consistency. After a transaction has started, it must be successfully completed, or SQL Server undoes all of the data modifications made since the transaction started.

SQL Statements affecting Transactions

BEGIN TRANSACTION

This indicates the start of a logical transaction and must be issued explicitly. When the first SQL statement that alters the database in some way is issued after the BEGIN TRANSACTION statement the changes will be stored in the log until the transaction is closed.

COMMIT TRANSACTION

This indicates to the database that the transaction is complete.

All changes made will be marked as permanent and any resources (locks) held by the transaction will be released.

ROLLBACK TRANSACTION

This indicates to the database that all SQL statements issued since the initial BEGIN TRANSACTION statement must be undone and any resources (locks) held by the transaction will be released. The transaction will be closed.

Transaction Processing and Locking

Whilst a transaction is in progress any rows affected (i.e. added, changed or deleted) by any SQL statement will be locked. This is so that other processes cannot access 'dirty' data (i.e. where the data may be inconsistent). As soon as the COMMIT TRANSACTION is issued then the resources (locks) will be released.

How does SYSPRO handle Transaction Processing?

There are three standard SYSPRO functions to handle Transaction processing, they are:

BEGIN-TRANSACTION

ROLLBACK-TRANSACTION

COMMIT-TRANSACTION

The following fields are defined in linkage (LINK.WRK).

05 LINK-SQL-TRANSACT PIC X.

* Transaction in progress

* Y - Yes

05 LINK-SQL-TRAN-TEXT PIC X(40).

* Transaction description

* eg 'Adding invoice 123456'

05 LINK-SQL-TRAN-STAT PIC X.

* Transaction status

* Blank – completed ok

* Y – In progress

* R – Rolled back (SQL)

* E – Failed (ISAM)

These functions together with the linkage fields provide the functionality to issue the appropriate SQL statements. The following illustrates typical usage of these new functions.

* Define the transaction description

01 TRAN-TEXT-MSG.

03 FILLER PIC X(15) VALUE “Adding invoice “.

03 TRAN-TEXT-INV PIC X(6).

*

**********************************************************

** Routine to illustrate using Transaction Processing **

**********************************************************

POST-FUNCTION.

PERFORM POST-FUNCTION-1 THRU POST-FUNCTION-END.

POST-FUNCTION-1.

*

** Setup transaction description and start transaction

MOVE INVOICE-NUMBER TO TRAN-TEXT-INV.

MOVE TRAN-TEXT-MSG TO LINK-SQL-TRAN-TEXT.

PERFORM BEGIN-TRANSACTION.

*

{Coding to add, updated or delete a record}

PERFORM COMER.

IF NOT STAT-OK

GO TO POST-FUNCTION-END.

*

{More coding to add, updated or delete a record}

PERFORM COMER.

IF NOT STAT-OK

GO TO POST-FUNCTION-END.

*

PERFORM COMMIT-TRANSACTION.

POST-FUNCTION-END.

The COMER function will detect if a transaction is in progress and if a failure is detected then it will perform the following.

  1. Display a message that the transaction has failed. The message will take the form of:

    An unexpected problem was detected during a transaction
    Current transaction     Adding invoice 123456

    The transaction has been rolled back and will need to be entered again.
    You may need to correct any problem before you attempt re-entry
    Please contact your system administrator if this problem persists.

    Where the current transaction description will be inserted by the program that was being run.

  2. Issue a Rollback statement

  3. Output a record to the job logging file

  4. Exit from the COMER leaving the status as not STAT-OK and the programmer should check the status and exit to the end of the transaction.

Note that for a C-ISAM based system the above logic will be performed except that the message will be different in that the transaction has terminated abnormally.

Important note about COMER inside a transaction

By default when you issue a PERFORM COMER function it will detect any file errors, display a message and branch to ENDJOB so that the program terminates gracefully.

However when inside a transaction the default behaviour is to detect any file errors, display a message and then continue with the processing - i.e. by default it DOES NOT BRANCH TO ENDJOB.

If you wish to ensure that any unexpected file error from within a transaction exits your program you can move 'E' to the field COMER-TO-ENDJOB.

For example you will often use the following code fragment when beginning a transaction:

PERFORM BEGIN-TRANSACTION.

MOVE "E" TO COMER-TO-ENDJOB.

Note that when you change the value of COMER-TO-ENDJOB it's a good idea to check that the program does not inadvertently change it's value back again - e.g. to a 'Y'.

Nested Transactions

SQL Server allows the concept of nested transactions but only handles the data integrity at the outer level.

SYSPRO maintains a flag LINK-SQL-TRANSACT that identifies whether there is a current transaction if progress. Note that it's in the linkage section as transactions can remain open across programs.

It is up to the programmer to ensure that the transaction is not started if one is already in progress. In addition the programmer must COMMIT or ROLLBACK the transaction at the appropriate time.

C-ISAM based systems

Note that the concept of Transaction Processing is not applicable in a C-ISAM environment. You can use the transaction processing functions but they have a different effect on a C-ISAM based company.

  • The BEGIN-TRANSACTION statement is documentary - except for the Job logging information

  • The COMMIT-TRANSACTION statement will release all record locks

  • The ROLLBACK-TRANSACTION statement will release all record locks and MUST NOT be used to undo any file changes

It is suggested that the transaction processing statements are used whether the system is designed for C-ISAM or SQL as they will perform the appropriate functions in the given environment.

Notes on Transaction Processing

  • A program should not close a file that is still being used in an open transaction.

  • Once a transaction has begun it should be either be committed or rolled back within a reasonable time. Generally a transaction should not be open during operator input as this may lead to the transaction being opened for an excessively long time. This holds system resources and prevents other users accessing the same data causing blocking.

  • Once a transaction has begun it should be either be committed or rolled back without attracting an 'excessive number of locks'. Although SQL Server allows a very large number of locks to be acquired it can have a detrimental effect to the multi-user capability of the system causing blocking of other users.

    for example if you were to modify a large number of rows in a table, SQL server may decide to 'escalate' it's locking mechanism to a page or even table lock. This will prevent anyone else from accessing that table until the transaction is closed.

    In addition the C-ISAM version should not typically attract more than about 50-100 locks. This value is a guideline and each system can impose different limits depending on it's configuration and the number of (concurrent) users.

  • When using multiple programs to handle file updates care must be taken to ensure that the transaction is handled appropriately, including the possibility of a rollback situation.

  • It is recommended that you do NOT explicitly use the ROLLBACK-TRANSACTION function in your program, rather you let the system call the function when COMER detects a problem.

Job Logging and Transaction Processing

To improve system integrity the Job Logging system will be used to track the status of a transaction as follows:

  • When a BEGIN-TRANSACTION is issued the transaction text will be placed in the job logging message field and a flag set in the job logging file that a transaction was started.

  • When a COMMIT-TRANSACTION is issued the job logging message will be cleared and the flag cleared to indicate that the transaction has completed successfully.

  • When a ROLLBACK-TRANSACTION is issued the job logging message will be retained and the Transaction flag will be set to indicate a rollback has occurred.

The Job Logging system has been enhanced to allow selection of Active and Failed transactions both for the report and screen display.

Timestamps and Optimistic Concurrency Control

Many SYSPRO programs use the SQL Server Timestamp capability to handle data contention. This uses Optimistic Concurrency Control. See the topic SQL Timestamp for more information.

SQL Exclusive Locking

There are a relatively small number of SYSPRO programs that require exclusive use of a file/table. They are generally Balance/Period end programs and Distribution reports. See the topic Exclusive Locking for more information.

See also

SQL Server Tuning, BEGIN-TRANSACTION, ROLLBACK-TRANSACTION, COMMIT-TRANSACTION, SQL Timestamp, Exclusive Locking


SQL Timestamp

Many SYSPRO programs use the SQL Server Timestamp capability to handle data contention. This uses Optimistic Concurrency Control.

Optimistic Concurrency Control

When using Transaction Processing there is a system overhead. This includes row locks on the data affected by the transaction together with the transaction logs that have to be maintained. In addition other users may be blocked from accessing data being affected by the transaction.

However in many instances it is fairly unlikely that the data is being changed by one user whilst another is trying to change the same data.

For example the A/R Terms Code maintenance program is unlikely to be used very regularly. The Terms codes certainly don’t change every day and usually it is one operator’s responsibility to ensure that the terms codes are correct so concurrent updates are extremely unlikely.

Optimistic Concurrency Control is a technique that can be used to avoid the system overhead of Transaction Processing.

Optimistic Concurrency Control makes use of the TimeStamp column defined against each SYSPRO table. SQL Server maintains an internal timestamp field against the database. This is simply a number that is incremented by one whenever any data is changed in the database. When SQL Server changes a row in a SYSPRO table the current value of the timestamp against the database replaces the existing value of the TimeStamp column and the database timestamp is incremented by one.

Therefore a program can read and save the current value of the TimeStamp column against the item being accessed. When/if the user attempts to save any changes, the program can compare the latest value of the TimeStamp with the saved value. If they are the same then the update can take place otherwise the user will be informed that the data cannot be updated due to subsequent changes having been applied by another user.

In this case no locks are acquired at all and in the event of a program failure there is no lock to be released.

Applying Optimistic Concurrency Control to a SYSPRO Program

To enable this method of Optimistic Concurrency control the SYSPRO program simply has to follow these steps:

  1. Save the current value of the TimeStamp column after reading the record. This is stored in the field TIMESTAMP-BIN after a xxxxxx-READ-LOCK statement. The field TIMESTAMP-SAV is defined in the standard copybooks for this purpose.

    PERFORM TBLART-READ-LOCK.
    MOVE TIMESTAMP-BIN TO TIMESTAMP-SAV.
    IF STAT-LCK

  2. Immediately before rewriting the record restore the saved value of the timestamp.

    MOVE TIMESTAMP-SAV TO TIMESTAMP-UPD.
    PERFORM TBLART-REWRITE.
    PERFORM COMER.

  3. If the COMER function fails with STAT-INVALID-TIMESTAMP then the update failed. The program will not exit via ENDJOB when this error occurs.

See also

SQL Server Tuning, Transaction Processing, Exclusive Locking


SQL Exclusive Locking

There are a relatively small number of SYSPRO programs that require exclusive use of a file/table. They are generally Balance/Period end programs.

Each program that needs to acquire exclusive locks should be enhanced for SQL Server as follows.

Before opening any files exclusively the program needs to detect if these files are 'in use' this is done using a new CHECK-FILES-IN-USE function. This function will call a program that will verify the file usage and show any operators using the files passed. If all the files are not being used then the program should begin a transaction and then open the files exclusively. Upon completion the transaction must be committed.

See the following code fragment - bold indicates new syntax

*

** Check if files are being used

MOVE “ARSMST ARSDET” TO CHECK-FILES-LIST.

PERFORM CHECK-FILES-IN-USE.

IF FILES-IN-USE

GO TO ENDJOB.

*

** Lock files exclusively

PERFORM BEGIN-TRANSACTION.

*

PERFORM ARSMST-BUILD-AND-OPEN-IO-LOCK.

PERFORM COMER.

*

PERFORM ARSDET-BUILD-AND-OPEN-IO-LOCK.

PERFORM COMER.

*

ENDJOB.

PERFORM ARSMST-CLOSE.

PERFORM ARSDET-CLOSE.

*

PERFORM COMMIT-TRANSACTION.

*

PERFORM QUIT-DS.

EXIT PROGRAM.

Please note the following.

  • When a program issues a XXXXXX-READ (without any lock) then this read will be successful on a SQL Server based system even if the file is opened exclusively by another program. The file handler will use a WITH (NOLOCK) phrase to ignore any exclusive locks. Thus Queries may still be run when Balance/Period end or Distribution report programs are being run.

  • Programs that change a file in any way (including write, rewrite, delete statements) will prevent exclusive file usage programs from being run. This will be detected by the CHECK-FILES-IN-USE function which will look at the IMPPRG.IMP file.

  • The IMPPRG.IMP file contains a space after the file name to indicate that the program can read/update/write data into the file. Note that an ! (exclamation mark) after the file code indicates exclusive access.

  • The SQL file handler will issue a SELECT TOP 1 * FROM Table WITH (TABLOCKX) statement when an XXXXXX-BUILD-AND-OPEN-IO-LOCK is issued. This will hold an exclusive lock when issued within a transaction and will be released when the COMMIT-TRANSACTION statement is issued.

  • When using Transaction Processing care should be taken when printing an audit of what has happened. Remember that any change processed may be rolled back if there is a subsequent failure. It is recommended that a list of all phases processed is only printed after a successful COMMIT-TRANSACTION. In addition it is often worth testing whether the program has reached the ENDJOB function when a phase was in process so you can issue a message to the audit log.

The CHECK-FILES-IN-USE function

The CHECK-FILES-IN-USE function calls the program called IMPUSR and is passed a space separated list of files. IMPUSR then displays those users who are using that file in any program. If no users are using the file(s) then the program will return an appropriate status.

See also

SQL Server Tuning, Transaction Processing, BEGIN-TRANSACTION, ROLLBACK-TRANSACTION, COMMIT-TRANSACTION, SQL Timestamp, CHECK-FILES-IN-USE


SQL Server User Defined Tables

SYSPRO SDK

SQL Server

Accessing User Defined SQL Tables

Introduction

This article assumes that you have a Net Express program and want to access a user defined table that resides in a SYSPRO database - and that you want to use ISAM functions (such as OPEN, READ, READ NEXT, WRITE, REWRITE, CLOSE etc.) to access the table.

Note that you can elect to access your user-defined tables in a SYSPRO or non-SYSPRO database by issuing your own SQL statements (such as SELECT, INSERT, UPDATE, DELETE etc.) using the SQL Server optimized functions available when using SQL.PRO. See the topic SQL Server Tuning Code for information about how to use these functions.

The remainder of this topic assumes that you want to use ISAM functions to access your user defined table.

An example has been used to help explain exactly what needs to be performed. In this example it is assumed that the user-defined table has a file code of CUSMST and the table will be called CustomMaster. You should insert you names as appropriate.

Creating the Record Layout

Firstly you should create a record layout called CUSMST.MAC in the following location:

\rnd60\source\copy60\CUSMST.MAC

The record layout should conform to the rules for the SYSPRO Data Dictionary.

Below is an example CUSMST.MAC

**************************************************************

* SYSPRO *

* Copyright (c) 1994-2005 SYSPRO Ltd. All rights reserved. *

**************************************************************

* Record layout : CUSMST.MAC *

* Description : Custom Master *

* @(#) Version : 6.0.000 *

* Last updated : 2005/01/12 09:00 *

* Record length : 100 *

* Key length : 30 *

* Data file : $d$cCUSMST$e *

* Module : CUS *

* Table name : CustomMaster *

**************************************************************

* Alternate idx : CUSMST-IDX-BARCODE Bar code *

* : CUSMST-BARCODE Bar code *

* : CUSMST-STK Stock code *

**************************************************************

01 CUSMST-REC.

03 CUSMST-KEY.

05 CUSMST-STK PIC X(30).

* SQL=StockCode

* Stock code

03 CUSMST-BARCODE PIC X(20).

* SQL=BarCode

* Bar code

03 CUSMST-COUNT PIC 9(12).

* SQL=BarCodeCount

* Number of bar code scans

03 CUSMST-UPDATE PIC 9(8).

* SQL=LastResetDate

* Date scan count last reset

03 FILLER PIC X(30).

This includes a comment header defining the table description and table name, a list of each field with a data type definition (PIC) and an associated column name (SQL=). You must ensure that the primary record and key length defined in the comment header are correct.

In addition, in this example there is an alternate index on the bar code field.

You can use the LENGTH utility supplied as part of the SYSPRO SDK to verify the record length is correctly defined. From a command prompt type:

CD \RND60\SOURCE\COPY60

LENGTH CUSMST.MAC

Importing the Record Layout into the Data Dictionary

Verify that the Data Dictionary configuration file TOOLKIT.INI in the SYSPRO base directory as a SRCNEW= entry that points to your source folder. For example:

SRCNEW=\rnd60\source

Load SYSPRO and run the Data Dictionary listview program using File, Run, DDSMEN. A useful tip is to add DDSMEN to your favorites menu and run it from there.

Select Functions, Import... and verify that the path used for the import is \rnd60\source\copy60

Enter CUSMST and click 'Import...' - this will validate and import the record layout.

If any errors are detected a report will be generated. In this case correct the errors described and re-run the import.

When successfully imported use 'Close' to return to the Data Dictionary listview.

You can manually verify that the record layout was imported successfully by selecting CUSMST from the listview and use Edit, View... to check the imported columns. This shows the file header information and details of each column, including the column name and data size.

The custom record layout has now been successfully imported into the SYSPRO Data Dictionary.

You can now exit from SYSPRO.

Generating SEL and CFL copybooks

Before your can use ISAM verbs, such as READ or WRITE, to access your custom table you need to create a copybook defining the SELECT statement to be incorporated into your source code and a File logic copybook containing standard functions to access your custom table. This is done as follows:

Ensure you have a folder called:

\rnd60\source\copy60\new

Load SYSPRO and run the Data Dictionary listview program DDSMEN.

Select Functions, Export...

Select Single and enter CUSMST

Select the following three check boxes:

Record layouts (MAC)

Select copybooks (SEL)

File logic (CFL)

And click 'Export...'

This will generate the following files:

\rnd60\source\copy60\new\CUSMST.MAC (record layout)

\rnd60\source\copy60\new\CUSMST.SEL (select copybook)

\rnd60\source\copy60\new\CUSMST.CFL (file logic copybook)

Note these are output to the COPY60\NEW folder so they do not automatically overwrite any existing copybooks in COPY60.

You should exit from SYSPRO and move these three copybooks up one level to COPY60.

The CUSMST.SEL copybook contains the SELECT statement to be incorporated into your source code. See the following example:

**************************************************************

* SYSPRO *

* Copyright (c) 1994-2005 SYSPRO Ltd. All rights reserved. *

**************************************************************

* Copybook : CUSMST.SEL *

* Description : Custom Master *

* @(#) Version : 6.0.000 *

* Last updated : 2005/01/12 09:34 *

**************************************************************

SELECT CUSMST

ASSIGN CUSMST-DATA

ORGANIZATION INDEXED

ACCESS DYNAMIC

LOCK MANUAL WITH LOCK ON MULTIPLE RECORDS

FILE STATUS IS STAT-CODE

RECORD KEY IS CUSMST-KEY

ALTERNATE KEY IS CUSMST-IDX-BARCODE

= CUSMST-BARCODE CUSMST-STK.

The CUSMST.CFL copybook contains various functions to handle all aspects of the file logic required to access your custom table. The following is a small fragment from this copybook:

**************************************************************

* SYSPRO *

* Copyright (c) 1994-2004 SYSPRO Ltd. All rights reserved. *

**************************************************************

* Copybook : CUSMST.CFL *

* Description : Custom Master *

* Copybook type : File handling for SQL/ISAM files *

* @(#) Version : 6.0.000 *

* Last updated : 2004/06/28 09:00 *

**************************************************************

GO TO CUSMST-FIO-END.

* Ensure code doesn't 'fall thru'

CUSMST-BUILD-AND-OPEN-IO-COMER.

PERFORM CUSMST-BUILD-AND-OPEN-IO.

PERFORM COMER.

*

CUSMST-BUILD-AND-OPEN-IO.

PERFORM CUSMST-BUILD-DATA.

OPEN I-O CUSMST.

MOVE CUSMST-DATA TO ERRFIL.

MOVE "CUSMST" TO ERRFCD.

MOVE ERROP TO ERRMES.

MOVE SPACES TO ERRKEY.

Other functions defined in this copybook include:

CUSMST-START-GE.

CUSMST-START-LT.

CUSMST-START-LE.

CUSMST-START-GT.

CUSMST-READ.

CUSMST-READ-NEXT.

CUSMST-READ-PREV.

CUSMST-WRITE.

CUSMST-REWRITE.

CUSMST-DELETE.

CUSMST-CLOSE.

CUSMST-UNLOCK.

In this example you will notice that the CUSMST.MAC copybook has been exported. It is recommended that you use this 'exported' version as it will have been formatted exactly the same way that standard SYSPRO record layouts are formatted.

Using the Copybooks in your source code

You are now ready to include these copybooks into your source code.

For example a program outline from a custom program could look as follows. The lines marked '000' demonstrate the use and placement of the custom table copybooks.

**************************************************************

** SYSPRO **

** Copyright (c) 1994-2005 SYSPRO Ltd. All rights reserved.**

**************************************************************

** Program name : CUS001 **

** Description : SYSPRO SDK Sample Source code Program **

** Run from menu : Yes **

** Can be secured: Yes **

** Owner : Core **

**************************************************************

*

* Date Init PDR Description

000 * 12/01/05 RJH none Sample source code to demonstrate use

* of custom table (CUSMST)

FILE-CONTROL.

*

000 COPY "CUSMST.SEL". *> Custom master table SELECT copybook

COPY "ADMREP.SEL". *> Printer SELECT copybook (mandatory)

*

DATA DIVISION.

FILE SECTION.

*

000 FD CUSMST.

000 COPY "CUSMST.MAC". *> Custom master record layout

*

FD ADMREP.

COPY "ADMREP.MAS". *> Report record layout (mandatory)

*

WORKING-STORAGE SECTION.

01 WHAT-STRING VALUE "@(#) Program version .000".

03 FILLER PIC X(25).

03 VERS PIC 9(3).

01 WHAT-DUMMY PIC X(2) VALUE X"0D0A".

*

COPY "CUS001.CPB". *> Dialog system data block copybook

COPY "DSCTL.WRK". *> Dialog system control block

*

COPY "STANDARD.WRK". *> Common working storage copybook

COPY "WWLINK.WRK". *> Common IMPSTD copybook

COPY "LNK.WRK". *> Copy LINK copybook

01 LNK2 PIC X. *> Dummy 2nd linkage copybook

*

LINKAGE SECTION.

COPY "LINK.WRK". *> Standard linkage

01 LINK2 PIC X. *> Dummy 2nd linkage

*

PROCEDURE DIVISION USING LINK, LINK2.

COPY "PROBEGIN.PRO".

000 COPY "CUSMST.CFL".

*

** Build and open Custom table name

PERFORM CUSMST-BUILD-AND-OPEN-IO-COMER.

*

** Sample code to read custom table

MOVE "B100" TO CUSMST-STK.

PERFORM CUSMST-READ.

IF NOT STAT-OK

PERFORM ITEM-NOT-FOUND.

** Rest of your code goes here

*

*

**************

** Endjob **

**************

CANCELREQ.

REGISTER-MESSAGES.

HOF.

ENDJOB.

000 PERFORM CUSMST-CLOSE.

PERFORM QUIT-DS.

EXIT PROGRAM.

Generating a SQL Server file handler

Until now your custom table can be accessed as an ISAM file with the name CUSMST.DAT.

However the requirement is to be able to seamlessly allow this table to reside on SQL Server. This requires the generation of a SQL file handler. The purpose of the SQL file handler is to translate the ISAM verbs defined in the functions in CUSMST.CFL (READ, WRITE, REWRITE etc.) to SQL Server statements (SELECT, INSERT, UPDATE etc.).

Before generating the SQL file handler for CUSMST ensure you have the file handler template that is provided as part of the SDK. It is called:

\rnd60\source\DDST01.TEM

Ensure you have a folder called:

\rnd60\source\fh

Then you should follows these steps:

Load SYSPRO and run the Data Dictionary listview program (DDSMEN).

Select Functions, Export...

Select Single and enter CUSMST

Select the checkbox called 'File handlers (FH??????.CBL)'

Click 'Export...' - this will generate the following SQL File Handler source code:

\rnd60\source\fh\FHCUSMST.CBL

Exit SYSPRO

You should now compile this SQL file handler as follows:

- Load a Net Express command prompt and type:

- CD \rnd60\source\fh

- COMPILE FHCUSMST

- This should compile clean. If so it will have generate your SQL file handler. This resides in the base\fh folder. For example it will be called:

\rnd60\base\fh\FHCUSMST.GNT

Creating your custom table in SQL Server

If required you can use the Data Dictionary system to generate a script that can be used to physically create your custom table in SQL Server.

This is done as follows:

Load SYSPRO and run the Data Dictionary listview (DDSMEN).

Select Functions, Export...

Select Single and CUSMST

Select the checkbox 'Create table script (TABLE.SQL)'

Click 'Export...'

This creates a SQL script file called:

\rnd60\source\TABLE.SQL

Exit SYSPRO.

You should now load the SQL Server Query Analyzer and log into your SYSPRO database. You will need to log in with sufficient permission to add tables - such as 'sa'.

Use File, Open and enter \rnd60\source\TABLE.SQL

Run the script.

This creates the table together with all the column definitions and primary and alternate keys.

Running your application

When your application runs from within SYSPRO it is the file name that determines whether your custom table will be handled as an ISAM file or a SQL table.

How does this work?

When a program issues any ISAM verb (READ, WRITE, UPDATE etc.) the Net Express run time system normally calls an ISAM library called mffh.dll.

However the SYSPRO compiler support batch files (e.g. COMPILE.BAT) reference a directive file (COMPILE.DIR) that contains the directive:

CALLFH"IMPFHX"

This causes the Net Express run time system to call the SYSPRO program IMPFHX instead of mffh.dll whenever an ISAM verb is processed. This has been shipped as part of IMPACT.EXE so is always available to every SYSPRO program.

Therefore whenever an ISAM verb is executed the program IMPFHX is invoked. This looks at the file name being passed and if it starts 'SQL' it calls the SQL file handler in the base\fh folder otherwise it assumes it's a regular ISAM file and calls mffh.dll.

In this way you can use ISAM verbs to access your custom file/table.

When you use the CUSMST-BUILD-DATA function (or any other function that calls it) it will detect if the company is an ISAM or SQL company and will build an appropriate file name.

For SQL server based companies the file name will begin 'SQL-FHCUSMST'. The exact structure of this special file name is defined in SQLFILE.WRK.

Other access to your custom table

When running on SQL Server you can also use virtually any SQL statement to access your custom table. For example you may wish to efficiently JOIN, sort or select specific columns from your tables together with the regular ISAM access.

See the topic SQL Server Tuning Code for information about how to do this.

See also

SQL Server tuning code, Transaction Processing, Transferring data between ISAM and SQL, SQL Server Tuning more than 200 columns


Transferring data between ISAM and SQL

This topic covers how to transfer data from ISAM to SQL and from SQL to ISAM.

A utility program (IMPSQM) has been developed to assist developers in transferring data between ISAM and SQL Server. This utility provides a number of functions required for the transfer process. These functions are described in detail below.

As part of the Software Development Kit the program SDKSQM has been developed in SYSPRO 6.0 and Encore 5.1 that provides a user-interface to the functions described in this topic. This is useful for a developer or tester to use the functions without having to develop a program to call IMPSQM.

You may want to transfer data between C-ISAM and SQL Server for several reasons.

To (temporarily) transfer data from SQL to ISAM for performance reasons

There are some cases where business logic requires a large data processing load. It is possible that the performance of the business function is much slower in a SQL Server environment. In these cases you can transfer the data from a SQL Server table to a C-ISAM file and then process the C-ISAM file.

If required any resultant changes can then be transferred back to the SQL Server table.

Initial setup of a SQL based company

If you have data in a C-ISAM file and there is a table in a SQL Server database that has the same structure then you can use this utility to transfer the ISAM data to the SQL table.

To synchronize SQL/ISAM companies for testing purposes

When testing and comparing ISAM and SQL Server functions it can be useful to transfer data between the systems so that the same data is being used in the comparisons.

Transferring data from a SQL Server table to C-ISAM

To transfer data from a SQL Server table to a C-ISAM indexed file you should setup the Input parameters shown below and then call the program IMPSQM.

Input parameters

IMPSQM-FUNCT

This must contain the value TOISAM.

IMPSQM-FILE

This is the 6 character file code that corresponds to the table name to be transferred. For example this will contain SORMST for the Sales Order Master table.

IMPSQM-PARENT

This field is only required when the file code defined in IMPSQM-FILE is a copy of another file.

For example if IMPSQM-FILE is defined as MRPSOH (MRP snapshot sales order header) which is an exact copy of the structure of the Sales Order Master file - you must move in SORMST to this field. See the 'Derived from' section in the record layout copybook to view the parent file code (in this example see MRPSOH.MAC).

IMPSQM-PATH

If you leave this field blank then the path to the C-ISAM file will be built using the normal ISAM build logic. Generally the file resides in the data directory with a company id prefix etc.

You can specify a file name (optionally including a path) that will be used as the file name of the extracted C-ISAM file. If required this could be a temporary file name.

Output parameters

IMPSQM-COPIED-OK

This field indicates the status of the transfer.

Y - OK

IMPSQM-PATH

This field returns the actual path to the C-ISAM file. This saves you having to build the path yourself.

Sample code

* Transfer the Sales Order Master table from SQL to ISAM

MOVE SPACES TO IMPSQL-LINK.

MOVE "SORMST" TO IMPSQM-FILE.

MOVE "TOISAM" TO IMPSQM-FUNCT.

MOVE IMPSQM-LINK TO LINK-EXTRA.

*

MOVE "IMPSQM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

MOVE LINK-EXTRA TO IMPSQM-LINK.

MOVE SPACES TO LINK-EXTRA.

*

IF IMPSQM-STAT = "Y"

PERFORM PROCESS-ISAM-SORMST-DAT.

Notes

Version 6.0.002 of IMPSQM has substantial speed improvements over previous versions. It is recommended to use this version or later.

Transferring data from a C-ISAM file to a SQL Server table

To transfer data from a C-ISAM file to a SQL Server table you should setup the Input parameters shown below and then call the program IMPSQM.

Input parameters

IMPSQM-FUNCT

This must contain the value TOSQL.

IMPSQM-FILE

This is the 6 character file code that corresponds to the table name to be transferred. For example this will contain SORMST for the Sales Order Master table.

IMPSQM-PARENT

This field is only required when the file code defined in IMPSQM-FILE is a copy of another file.

For example if IMPSQM-FILE is defined as MRPSOH (MRP snapshot sales order header) which is an exact copy of the structure of the Sales Order Master file - you must move in SORMST to this field. See the 'Derived from' section in the record layout copybook to view the parent file code (in this example see MRPSOH.MAC).

IMPSQM-PATH

If you leave this field blank then the path to the C-ISAM file will be built using the normal ISAM build logic. Generally the file resides in the data directory with a company id prefix etc.

You can specify a file name (optionally including a path) that will be used as the file name of the extracted C-ISAM file. If required this could be a temporary file name.

IMPSQM-STAY-CON

This is a flag used to indicate that the IMPSQM program must stay connected to SQL Server unless otherwise specified.

Setting this flag to Y reduces the overhead when many C-ISAM files are to be transferred to SQL Server in quick succession. When set to Y the disconnect function must be used to terminate the connection - see below. Note that when calling IMPSQM with this flag set to Y requires the use of CALL-PROGRAM-NO-CANCEL. Remember to cancel IMPSQM from memory when you have finished. Using CALL-PROGRAM to disconnect will do this.

IMPSQM-RETAIN

This is a flag to be used where the SQL Server table is not to be cleared before the transfer takes place.

Setting this flag to Y indicates that the C-ISAM data is appended to rows in the existing table.

Note that the default is that the all existing rows are removed from the table before the transfer takes place.

Output parameters

IMPSQM-COPIED-OK

This field indicates the status of the transfer.

Y - OK

Remarks

When transferring data from C-ISAM to SQL Server the utility takes advantage of the performance of the BULK-INSERT SQL Server command. This requires a system administrator (sa or near equivalent) level of database access.

There is an option against the Company Setup program (against the SQL Server Tab) that allows you to define the Login, Password and a temporary folder to be used during the transfer process. This must be setup before you can use the ISAM to SQL transfer (TOSQL) function.

You can verify the validity of this setup by using the check login function. See below.

Sample code

* Transfer the Sales Order Master file from ISAM to SQL Server

MOVE SPACES TO IMPSQL-LINK.

MOVE "SORMST" TO IMPSQM-FILE.

MOVE "TOSQL" TO IMPSQM-FUNCT.

MOVE IMPSQM-LINK TO LINK-EXTRA.

*

MOVE "IMPSQM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

MOVE LINK-EXTRA TO IMPSQM-LINK.

MOVE SPACES TO LINK-EXTRA.

*

IF IMPSQM-STAT = "Y"

PERFORM SORMST-IN-SQL-FUNCTION.

* Second example...

* Transfer the Sales Order Master file to SQL and stay connected

MOVE SPACES TO IMPSQL-LINK.

MOVE "SORMST" TO IMPSQM-FILE.

MOVE "Y" TO IMPSQM-STAY-CON.

MOVE "TOSQL" TO IMPSQM-FUNCT.

MOVE IMPSQM-LINK TO LINK-EXTRA.

*

MOVE "IMPSQM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM-NO-CANCEL.

MOVE LINK-EXTRA TO IMPSQM-LINK.

MOVE SPACES TO LINK-EXTRA.

*

IF IMPSQM-STAT = "Y"

PERFORM SORMST-IN-SQL-FUNCTION.

Using the 'check login' function

When transferring data from C-ISAM to SQL Server the utility takes advantage of the performance of the BULK-INSERT SQL Server command. This requires a system administrator (sa or near equivalent) level of database access.

There is an option against the Company Setup program (against the SQL Server Tab) that allows you to define the Login, Password and a temporary folder to be used during the transfer process. This must be setup before you can use the ISAM to SQL transfer (TOSQL) function.

You can verify the validity of this setup by using the check login function described here.

Input parameters

IMPSQM-FUNCT

This must contain the value CHK-LOGIN.

Output parameters

IMPSQM-COPIED-OK

This field indicates the status of the connection.

Y - OK

Sample code

* Verifying the Login details against the Company Setup

MOVE SPACES TO IMPSQL-LINK.

MOVE "CHK-LOGIN" TO IMPSQM-FUNCT.

MOVE IMPSQM-LINK TO LINK-EXTRA.

*

MOVE "IMPSQM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

MOVE LINK-EXTRA TO IMPSQM-LINK.

MOVE SPACES TO LINK-EXTRA.

*

IF IMPSQM-STAT = "Y"

PERFORM START-ISAM-TO-SQL-TRANSFER

ELSE

PERFORM DISPLAY-LOGIN-NOT-SETUP.

Using the 'disconnect' function

When transferring data from C-ISAM to SQL Server the utility can be defined to retain the connection between transfers by moving Y to the field IMPSQM-RETAIN.

This requires a disconnect upon completion of all the required data transfers. This is described here.

Input parameters

IMPSQM-FUNCT

This must contain the value DISCON.

Output parameters

IMPSQM-COPIED-OK

This field indicates the status of the disconnection.

Y - OK

Sample code

* Disconnect IMPSQM from SQL Server

MOVE SPACES TO IMPSQL-LINK.

MOVE "DISCON" TO IMPSQM-FUNCT.

MOVE IMPSQM-LINK TO LINK-EXTRA.

*

MOVE "IMPSQM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

MOVE LINK-EXTRA TO IMPSQM-LINK.

MOVE SPACES TO LINK-EXTRA.

*

Requirements

Version: Included in Encore 5.1 issue 004 and later and Encore 5.0 issue 006 and later. Note

that Version 6.0.002 of IMPSQM has substantial speed improvements when transferring data from SQL to ISAM over previous versions.

Copybooks: standard

See also

CALL-PROGRAM, CALL-PROGRAM-NO-CANCEL, SQL Server Tuning


Printing Overview

The printing system provides straightforward and consistent functions to print reports and documents. These functions allow the programmer to concentrate on producing a report and not on the technology behind the scenes.

Also note that SYSPRO ships with a Report Writer. You can call the Report Writer from your application program. See Printing using the Report Writer.

More recent versions of SYSPRO make extensive use of SYSPRO Reporting Services (SRS) which makes use of Crystal reports. It is recommended that all new development uses SRS style of report generation.

Important - It is our intention that from SYSPRO 7 the vast majority of SYSPRO reports will be re-engineered using the SYSPRO Reporting Services (SRS) technology AND the older legacy reports removed. However we intend retaining this (legacy) logic so that 3rd party reports that have been generated using the functions documented here will still work as before. Also note that the Financial Report Writer and generic Report Writer still uses this technology - even for SYSPRO 7.

However for SYSPRO 7 the Print Offsets logic will be removed.

Introduction

The SYSPRO printing system relies on fixed width characters, including spaces, to ensure alignment of columns of data and their headings. This limits the number and types of Fonts that are supported in the Windows Environment but fortunately the Courier New True Type font is a good, scalable, general purpose font that can be used. The Font dialog box shows all fixed width fonts – bitmapped and vector (such as true type) – and includes printer based fonts supported by the driver.

Most SYSPRO reports print up to 132 columns of data however you can use up to 300 columns for custom development. The GL Report Writer and the SYSPRO Report Writer both allow up to 300 columns using these functions.

The default Font used for Windows printing is Courier New 7 point. This generally provides the full 132 column printing capability in portrait, depending on the margins. More columns can be used by printing in Landscape. Somewhere between 80 and 110 lines per page can be printed in Portrait – less in Landscape – this also depends on the paper size and margins.

Whilst sending text to the printer using the standard print functions the system calculates the lines per page and keeps track of the current line number. When the system determines that a head of form is required your own head of form (HOF) function will be called.

You can view the current number of lines per page using the Shift+F7 function within SYSPRO – this is stored in the linkage field L-PRT-LPP. For Windows printers this is a calculated field, for SYSPRO type printers (devices, disk file, spooler) this is configured against the printer.

When printing to a Windows printer it is possible to include a bitmap background for your report or document. This is especially useful for documents such as statements, delivery notes and invoices. To include a bitmap background simply move the name of the bitmap to the field L-WIN-BMP and the printed width to L-WIN-BMP-SFAC and the width unit of measure (mm or inches) to L-WIN-BMP-SMET. See PRINT-OPEN for further details.

Screen Preview and Email

The operator can toggle screen previewing On or Off using Shift+F4. When the preview is On the report is always spooled to the server and then presented to the operator a page at a time. The screen preview functions allow you to page forward or backward through the report – even jumping to the last page or to a specific page number. You can search for text (such as a customer name) to make finding the information required quick and easy.

The Windows screen preview is WYSIWIG and provides functions such as a zoom capability, being able to view the report together with it's bitmapped background, being able to print a range of pages or a single page.

When the Screen Preview is shown, and if the Office Automation module is installed, the operator may Email the report. You can pass a default email address to be used when the operator clicks on the Email push button by passing the address in L-WIN-EMAIL and a D in L-WIN-EML-F. note that it is actually the PRINT-CLOSE function that shows the preview and provides the Email function.

Note that the email function available from the screen preview does not send any associated bitmap. This is a limitation of the email function.

You can force a view-only preview function (disabling the Print, Email and Copy to clipboard functions) by moving Y to L-PRT-PREVIEW before the PRINT-OPEN and moving the word 'VIEWONLY' to LINK-EXTRA before the PRINT-CLOSE function

Printing text

To print a line of text move the text to be printed to the field SP-PRLINE and then use the WRITE-PRLINE-AFTER-1 function. This performs a single line skip (from the current/previous line) and then prints the current line of text. There are additional functions WRITE-PRLINE-AFTER-2, WRITE-PRLINE-AFTER-3 etc up to 9.

If more convenient you can move the number of lines to be skipped to the field SP-LINE-SKIP and the use WRITE-PRLINE-AFTER-SKIP function.

If one or more of the fields to be printed on your print line is potentially large (such as a stock code being 30 characters) but in practical cases is rarely this large then you can use print offsets so that the printing system will adjust the print layout in the unlikely event of the large field being full. Remember that the Print Offset logic will be removed for SYSPRO 7.

The function WRITE-PRLINE-AFTER-PAGE should be used to force a page skip before printing a line of text.

When using the PRINT-OPEN function you should note that a print dialog may be requested by the operator to allow them to select the printer or other printer settings at this time. The operator can cancel the report – in this case the program will branch to CANCELREQ. This is also true when printing to a disk file and requesting the disk file at run-time.

Once the report has completed you should use PRINT-CLOSE to finalise the report and start the screen preview or printing of the document. If you need to abort a print job and close the printer without printing anything (rare) then you should use PRINT-CLOSE-NO-PRINT which will return system resources.

Print dialog shown at run time

The operator can setup that the report is to 'Request Print Dialog' before the report is produced. This allows a printer selection to be made before the report is generated. In addition other printer settings, such as landscape can be set.

In this case the PRINT-OPEN function will request the print dialog by calling a standard Windows Dialog (when using Windows printing) or a similar SYSPRO program (when printing to other printer types).

The standard Windows print dialog can be passed a window handle to ensure that the Windows print dialog box remains in the foreground by making it a child of the window handle passed.

To provide this functionality you should add the following line of dialog just before you start the printing function:

MOVE-OBJECT-HANDLE WIN-MAIN S-WINHAN

Where WIN-MAIN is the current window or dialog box being shown. This can be a tickover dialog box if required.

Then, in your source code, just before the PRINT-OPEN function, you should move in the window handle to the linkage field LINK-PRT-HANDLE as shown in the example below:

MOVE D-S-WINHAN TO LINK-PRT-HANDLE.

PERFORM PRINT-OPEN.

Note that LINK-PRT-HANDLE is cleared after the PRINT-OPEN function.

Also note that, as the field LINK-PRT-HANDLE is in linkage, the handle may be moved in to this field from one program even if a second program is the one that issues the PRINT-OPEN function.

You must never attempt to use an invalid window handle as this can cause spurious errors at print time.

Printer types supported

The generic printer functions support many different types of physical printing on both mapped drive and client/server systems. The different types are shown below.

Windows printers | native Windows printer support
Devices | writes 'raw' data to a device such as LPT1: or a UNC name such as \\server\printer
Disk files | stores the report on a disk file – can be printed later
Spooler (temp files) | this printer type spools the report to a disk file and you can then define any operating system command or program to process this file
Spooler (Unix) | this is a Unix Server specific type of printing that can directly interface with the Unix spooler system

Note that not all printer options relate to all printer types. For example bitmap background can only be used for Windows printers.

Defining a printer for a specific program function

There are a number of places within SYSPRO that you can define a default printer for a function. These include:

  • Sales Order entry can setup a default printer for invoices, delivery notes, order acknowledgements and credit notes

  • Dispatch notes and dispatch invoices allow a printer to be defined

The printing system provides the GET-PRINT-BY-FUNCTION, SET-PRINT-BY-FUNCTION and CLR-PRINT-BY-FUNCTION functions to assist the programmer in setting up this functionality.

Sample code

MOVE "Demonstration report" TO L-PRT-TITLE.

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later. The ability to include a default email address is only available in Encore 5.1 issue 003 and later. The ability to call the preview in a view-only mode is only available in SYSPRO 6.0 issue 005 and later.

Copybooks: standard

See also

Print offsets, Printer per function, Printing using the Report Writer, Printing and Retaining a Spooled Report, PRINT-OPEN, WRITE-PRLINE-AFTER-1, WRITE-PRLINE-AFTER-SKIP, WRITE-PRLINE-AFTER-PAGE, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV, GET-PRINT-BY-FUNCTION, SET-PRINT-BY-FUNCTION


Print offsets

SYSPRO SDK

Printing

Printing Offsets

Offsets are used when potentially large fields are to be printed but an existing layout that caters for smaller fields is to be retained.

Note that the Print Offset logic will be removed for SYSPRO 7. You should consider recoding reports to use other printing technology.

To define an offset you pass a completely expanded print line (with all the fields at their maximum size) to the print routines and you pass an offset definition. The offset definition defines each field in the extended print line. The offset definition of each field consists of a 12 character string in the following format:

"aaa,xbbb,ccc"

where

aaa | indicates the field start position in the print layout passed to the print routine
x | indicates the offset type to be used (see below)
bbb | indicates the size of the field being offset
ccc | indicates the required start print position on the print line (excluding 1000 separators)

The various offset types include:

S | The alphanumeric field(s) following this position will be printed on the next line, should the current field not fit on the print line
X | The alphanumeric field(s) at this position will be printed on the next line, should it not fit on the print line
V | The numeric field (signed with 2 decimals) at this position will be edited to include 1000 separators and will be printed on the next line, should it not fit on the print line
B | As per offset type “V”, but negative fields will print inside brackets instead of having a trailing negative sign
P | As per offset “V” but for a cost or price field (signed with 5 decimals.

Below are examples of offsets.

01 HDG4.

02 STOCK PIC X(30).

02 FILLER PIC XX.

02 STOCK-DESC PIC X(30).

02 FILLER PIC X(3).

02 WAREHOUSE PIC X(2).

02 FILLER PIC X(3).

02 WAREHOUSE-DESC PIC X(30).

02 FILLER PIC X.

02 COST PIC Z(9)9.99999-.

02 FILLER PIC X.

02 STK-VAL PIC Z(11)9.99-.

02 FILLER PIC X.

02 QTY PIC Z(11)9.999-.

01 HDG4-OFFSETS.

02 FILLER PIC X(12) VALUE "001,S030,001".

02 FILLER PIC X(12) VALUE "031, 032,016".

02 FILLER PIC X(12) VALUE "063, 039,048".

02 FILLER PIC X(12) VALUE "102,P017,086".

02 FILLER PIC X(12) VALUE "120,V016,104".

02 FILLER PIC X(12) VALUE "137,X017,116".

MOVE HDG4 TO SP-PRLINE.

MOVE HDG4-OFFSETS TO SP-PRINT-OFFSETS.

PERFORM WRITE-PRLINE-AFTER-1.

Depending on the field sizes, the final report output could look as follows:

Stock code Description WH Description Price Value Qty

BB100-1001 Boy’s bicycle - Blue AA Bicycle warehouse 1,500.00000 4,500.00 3.000

BB200–100500-250 AA Bicycle warehouse 1,500.00000 1000.000

Boy’s bicycle - Red 1,500,000.00

MB300-1005 Men’s bicycle – Red MA Men’s Bicycle warehouse 2,250,000.00 500.000

4,500.00000

HB300-2005 Men’s Helmet – Blue HB Helmets warehouse 2.00000 30,000.00

15000.000

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1


Printer per Function

Defining a printer for a specific program function

There a number places within SYSPRO that you can define a default printer for a function. These include:

  • Sales Order entry can setup a default printer for invoices, delivery notes, order acknowledgements and credit notes

  • Dispatch notes and dispatch invoices allow a printer to be defined

The printing system provides the GET-PRINT-BY-FUNCTION, SET-PRINT-BY-FUNCTION and CLR-PRINT-BY-FUNCTION functions to assist the programmer in setting up this functionality.

These functions allow the appropriate printer information to be stored for a program function. This includes such details and the printer, paper size, source, margins, orientation, font, point size. The printer information is stored in the C-ISAM file called ADMPRF using the operator code and a 6 character function code. See the record layout ADMPRF.MAI for a list of the currently used codes. It is suggested that 3rd party developers start their codes with 'U'.

Worked example

The following worked example, using the Sales Order and Invoicing function, shows how to read, set and retrieve a specific printer for the invoice printing function. The function code for this example is SINV.

To see how this works in action run the Sales Order Entry program, click Preferences and then Printer Preferences. You will see a number of functions that can have a default printer set. Initially you will see the phrase

Printing of online invoices set to {Current printer} with a push button labeled Set…

This indicates that no specific printer has been set for that program function.

The message {Current printer} is defined in this program by the data block field D-OPR-IN-PRT. This is a 220 character field to allow for a 220 character printer name. The coding used by the Sales Order program to generate the text in this data block field is shown below:

GET-INVOICE-PRINTER-NAME.

MOVE "SINV" TO LINK-PRINT-FUNCT.

PERFORM GET-PRINT-BY-FUNCTION.

IF LINK-EXTRA = SPACES

MOVE "{Current printer}" TO D-OPR-IN-PRT

ELSE

MOVE LINK-EXTRA TO D-OPR-IN-PRT.

When you click on the Set... push button you will be prompted whether you want to set the current printer information for that function. When you confirm this the following coding will be used. (the GET-INVOICE-PRINTER-NAME function is performed so that the message is updated on the screen to reflect the new default)

SET-INVOICE-PRINTER-NAME.

MOVE "SINV" TO LINK-PRINT-FUNCT.

PERFORM SET-PRINT-BY-FUNCTION.

PERFORM GET-INVOICE-PRINTER-NAME.

When your report/document is about to be printed you can then use the following coding to set the printer for this function.

PRINT-INVOICE.

MOVE "SINV" TO LINK-PRINT-FUNCT.

PERFORM GET-PRINT-BY-FUNCTION.

IF LINK-EXTRA NOT = SPACES

MOVE "SINV" TO LINK-PRINT-FUNCT

MOVE "CHGPRT" TO WW-FUNCTION

PERFORM WW.

PERFORM PRINT-OPEN.

See also

Printing, Print offsets, GET-PRINT-BY-FUNCTION, SET-PRINT-BY-FUNCTION, CLR-PRINT-BY-FUNCTION, PRINT-OPEN, PRINT-CLOSE


Printing Using the Report Writer

The Report Writer can be invoked from an application program. This can be used to provide printing functionality without having to code the Report in your application.

To call the Report Writer directly from your application you should move the message '{Report}' to the field LINK-EXTRA and then pass the rest of the parameters in the copybook REPP80.LNK. This must be defined in LNK2 - see the source code example below.

You can pass a number of run-time properties including initial values for run-time user variables.

The SDK program SDKREP is a working demonstration showing how you can call the Report Writer passing various parameters.

Remember that the customer must be licensed to use the Report Writer module.

Sample code

*

** Working storage requirements

01 LNK2 PIC X(2300).

COPY "REPP80.LNK".

*

** Call the Report writer running report 'CUSTOM'

MOVE SPACES TO REPP80-LINK.

INITIALIZE REPP80-LINK.

MOVE LENGTH OF REPP80-LINK TO REPP80-LEN.

MOVE "CUSTOM" TO REPP80-REPORT.

MOVE "Y" TO REPP80-AUTORUN. *> Run report immediately

MOVE ZERO TO REPP80-TEST-MODE.

MOVE REPP80-LINK TO LNK2.

MOVE "{Report}" TO LINK-EXTRA.

*

MOVE "REPP80" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

Requirements

Version: Included in Encore 5.0 and later. The ability to pass initial values to the Report Writer requires SYSPRO 6.0 issue 005 or later.

Copybooks: standard

See also

Printing overview


Printing and Retaining a Spooled Report

The printing system has a flag (L-PRT-DELETE) that can be set to 'N' to indicate that the printer system should not remove any spooled report after it has been printed or previewed.

This flag should be set before the printer is opened (PRINT-OPEN) as shown in the following code fragment:

MOVE "N" TO L-PRT-DELETE.

PERFORM PRINT-OPEN.

When the printer is closed (PRINT-CLOSE) the printer system is invoked and typically the temporary spooled report will be removed. However by setting this flag the temporary spooled report file will be retained. The field L-PRT-FILENAME contains the name of the temporary spooled report file.

This could be used to save the report or to process it in some other way. Remember that this could lead to a large amount of disk space being utilized.

This flag is reset back to the default value after the PRINT-CLOSE function has completed.

On a standalone/mapped drive system the spooled report will always be retained when this flag is set.

On a client/server system the spooled report on the server will be retained, however any temporary files on the client will be removed as normal.

Sample code

MOVE "Retain spooled report demo" TO L-PRT-TITLE.

MOVE "N" TO L-PRT-DELETE.

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

*

** Now process temp spooled report

MOVE L-PRT-FILENAME TO REPORT-FILE-NAME.

PERFORM PROCESS-REPORT-FILE-NAME.

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 03 and later.

Copybooks: standard

See also

Print offsets, Printer per function, Printing using the Report Writer, PRINT-OPEN, WRITE-PRLINE-AFTER-1, WRITE-PRLINE-AFTER-SKIP, WRITE-PRLINE-AFTER-PAGE, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV, GET-PRINT-BY-FUNCTION, SET-PRINT-BY-FUNCTION


Special files overview

SYSPRO SDK

Special Files

IMP Files Overview

Introduction

When SYSPRO is installed various text files with an IMP extension are shipped as part of the product. These files are used by various programs as the source of their information.

Customized Import Files (*.IMP)

SYSPRO uses various ASCII text import files (*.IMP) to provide information about the standard system.

For example the file IMPPRG.IMP contains a list of all the standard SYSPRO programs. When you use the File > Run facility and browse on programs the IMPPRG.IMP file is used to provide the list of programs. This file is used elsewhere in SYSPRO – for example when you add a program to the Favorites menu the wizard uses IMPPRG.IMP to provide the default program description.

Whenever a SYSPRO program reads one of the standard text import files, once it has finished reading the standard import file, it will then look for a custom equivalent and append this information to it’s list.

When deploying custom programs it is recommended that you ship an equivalent set of custom text files in the custom program directory - on a client/server system these reside on the server. Note that there are some limitations to the total number of entries in the standard and custom import files. See the individual explanations for any limits.

It is not recommended that you edit the standard version of these IMP files.

Text import files include:

Standard | Custom | Notes
IMPPRG.IMP | CUSPRG.IMP | List of programs
IMPFIL.IMP | CUSFIL.IMP | List of files
IMPMEN.IMP | CUSMEN.IMP | List of items in menu
IMPMOD.IMP | CUSMOD.IMP | List of modules
IMPHLP.IMP | CUSHLP.IMP | On-line help redirector
IMPPRT.IMP | CUSPRT.IMP | Library of SYSPRO style printer attributes
IMPPSS.IMP | CUSPSS.IMP | Program function passwords
IMPSEC.IMP | CUSSEC.IMP | Security Activities and Fields

System setup file (IMPACT.INI)

When SYSPRO is installed the setup program creates an IMPACT.INI file in the work directory. This text file contains various settings and paths that are used as basic system wide information. This file can be maintained using the System Setup program from the main menu pull down.

It is not recommended that you add entries or change this file in any way, except by using the System Setup program. Invalid or incorrect entries in this file can cause the SYSPRO system to fail to work.

Custom program definition (CUSTOM.IMP)

The CUSTOM.IMP file should be used to define all your customized programs. It should be defined in your working directory (on the server in a client/server system).

The entries in the file are prefixed by a code that identifies whether the programs can be run by everyone (system-wide), or only for certain companies, groups or operators.

In addition it is possible to redirect a standard program to a customized program. For example if you wish to deploy a customized version of the Stock Code browse (INVBST) you can inform SYSPRO that every time INVBST runs it should call CUSBST instead.

Generic message file (IMPMSG.IMP)

The IMPMSG.IMP file contains a list of common messages used by SYSPRO. It resides in the program directory (on the server in a client/server system).

See also

IMPPRG.IMP, IMPFIL.IMP, IMPMEN.IMP, IMPMOD.IMP, IMPHLP.IMP, IMPPRT.IMP, IMPSEC.IMP, IMPACT.INI, CUSTOM.IMP, IMPMSG.IMP


IMPPRG.IMP

SYSPRO SDK

Special Files

IMPPRG.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPPRG.IMP file contains a list of all the standard SYSPRO programs, their description and which data files they access.

When you use the File > Run facility and browse on programs the IMPPRG.IMP file is used to provide the list of programs. This file is also used when you add a program to the Favorites menu the wizard uses IMPPRG.IMP to provide the default program description.

Defining a Custom file

When SYSPRO programs have completed reading the IMPPRG.IMP file they automatically look for a custom equivalent (CUSPRG.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO information - the operator simply sees a single list. The CUSPRG.IMP file must be in the same format as the standard file.

Programs that read IMPPRG.IMP and CUSPRG.IMP support a minimum of 4000 programs in total.

Sample IMPPRG.IMP file

This is an example of the first part of an IMPPRG.IMP file. Only the first 3 file codes per program are included to aid readability.

; IMPPRG.IMP - List of Standard SYSPRO 6.1 Programs

;

; Copyright (c) 1994-2009 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.1.059 Last updated : 2009/11/30 14:46

;

; Col Usage Notes

; ----- --------------------------------- ---------------------------

; 1-6 Program name 6 characters, ';' - Comment

; 8-47 Program description 40 characters

; 49 Program can be run from menu N - No

; 50 Program Component type Q - Query, S - Setup

; T - Transaction posting

; R - Retrieve, U - Utility

; C - Component

; 51 Program can be security protected N - No

; 52 Program is a browse program B - Yes

; 53 Program uses printer R - Yes, S - SRS-only report

; 55-57 Program for a specific Nationality All or USA, CAN

; 59+ List of files used by program If terminated by ! this

; indicates Exclusive access

; Max 100 files

;

; Sec Nat

;Prog Desc Men Rep Usage

;----- ---------------------------------------- - - - --- ------ ------ ...

;

; Module IMP - System Admin & Shared Programs

IMP002 Sales Analysis Transaction Maintenance - - - All ARSCTL ARSSTD SALCTL

IMP003 Inventory Document Print - - R All ADMOPR ADMPRA GTRDET

IMP005 WIP Trial Kitting - -B- All ADMOPR ADMSYS BOMROU

IMP006 List of BOM Cost/Work Centers - - R All BOMWRK BOMCST

IMP009 BOM Route Cards - - R All BOMROU BOMMOV BOMMST

See also

Special files overview


IMPFIL.IMP

SYSPRO SDK

Special Files

IMPFIL.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPFIL.IMP file contains a list of all the standard SYSPRO data files, their description and location information.

When you use the reindexing utility the IMPFIL.IMP file is used to provide the list of files available.

Defining a Custom file

When SYSPRO programs have completed reading the IMPFIL.IMP file they automatically look for a custom equivalent (CUSFIL.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO information - the operator simply sees a single list. The CUSFIL.IMP file must be in the same format as the standard file.

Programs that read IMPFIL.IMP and CUSFIL.IMP support a minimum of 4000 data files in total.

Sample IMPFIL.IMP file

This is an example of the first part of an IMPFIL.IMP file.

; IMPFIL.IMP - List of Standard SYSPRO 6.1 Data Files

;

; Copyright (c) 1994-2009 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.1.040 Last updated : 2009/11/20 16:07

;

; Col Usage Notes

; ----- --------------------------------- ---------------------------

; 1-6 File code 6 characters, ';' - Comment

; 8-47 File description 40 characters

; 49 File type C - C-ISAM & RDBMS

; I - C-ISAM only

; R - RDBMS only

; S - Sequential ASCII

; T - Temporary

; 51 File resides in working directory W - Yes

; 53 File prefixed by company id C - Yes

; 54 Exclude file from re-index X - Exclude file

;55-58 Record length (1-3600)

;60-62 Primary key length (1-100)

;64-81 Table name

;

; Wrk Rlen

;File Desc Typ Com Key Table

;----- ---------------------------------------- - - - ---- --- -----------

;Mod Activity Based Costing ABC Abc

ABCANL ABC Element Analysis C - C 210 25 AbcAnalysis

ABCELE ABC Element Descriptor C - C 380 6 AbcElement

ABCSTR ABC Element Structure C - C 100 37 AbcStructure

;Mod System Administration ADM Adm

ADMACC Admin Group Program Security I W - 20 12 AdmOperGroupProg

ADMARC Admin List Of Archive Types (IMPARC.IMP) S - - 1037 {import}

ADMB2B Admin Default XML/EDI Directory Paths I W C 341 66 AdmB2BPaths

ADMB2C Admin B2B Document Control C W C 380 3 AdmB2BControl

ADMB2E Admin B2B Failed Document Control I - C 380 3 AdmB2BFailedCtl

ADMB2F Admin B2B Failed Document Details I W C 740 28 AdmB2BFailed

;Alt 1 Operator code 674- 6, 1- 6, 7- 6, 13- 8, 21- 8

;Alt 2 Date of document 13- 8, 21- 8, 1- 6, 7- 6

ADMB2H Admin XML History Details I W C 640 88 AdmB2BHistory

;Alt 1 Document type 7- 6, 73- 8, 81- 8, 1- 6, 13- 60

;Alt 2 Date of document 73- 8, 81- 8, 1- 6, 7- 6, 13- 60

ADMBOS Admin Business Object Status I W - 1300 36 {none}

;Alt 1 Start date / time 93- 8, 101- 8, 1- 36

ADMCAL Admin Factory Calendar C W C 37 6 AdmCalendar

See also

Special files overview


IMPMEN.IMP

SYSPRO SDK

Special Files

IMPMEN.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPMEN.IMP file contains an indented menu structure that is used by the main SYSPRO menu.

Defining a Custom file

When the SYSPRO main menu has completed reading the IMPMEN.IMP file it automatically looks for a custom equivalent (CUSMEN.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO menu - the operator simply sees a single menu. The CUSMEN.IMP file must be in the same format as the standard file.

Sample IMPMEN.IMP file

This is an example of the first part of an IMPMEN.IMP file.

; IMPMEN.IMP - SYSPRO 6.1 Menu Structure

;

; Copyright (c) 1994-2010 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.1.000 Last updated : 2009/11/20 15:40

;

; Program Icon Description

; ------- ----- -----------------------------

P APS Menu + Accounts Payable

P APSPEN Query - Supplier Query

P Menu + Invoice Processing

P APSP10 Post - AP Invoice Posting

P APSP09 Post - AP Permanent Entries Posting

P IMP060 Post - AP Supplier-Customer Contra

P APSP80 Batch - Invoice Registration System

P APSP81 Rep - AP Exchange Rate Revaluation

P Menu + Payment Processing

P APSP95 Post - Payment Cycle Maintenance

P APSP25 Rep - Cash Requirements

P APSP35 Rep - Released Payments Report

S SRS106 Rep - AP Payment Register

P Menu + Reports

P APSP20 Rep - AP Trial Balance

P IMPL02 Rep - AP List of Suppliers

P APSP71 Rep - Purchase Analysis

P APSP73 Rep - Purchase Analysis History

P APSP21 Rep - Aged Analysis

P APSP75 Rep - AP Label Print

P APSP77 Rep - 1099 Label Print

P APSP52 Rep - AP Tax Distribution Report

P IMPL01 Rep - List of Banks

P IMPL27 Rep - AP List of Branches

P IMPL10 Rep - List of Currencies

P APSP72 Rep - AP List of Permanent Entries

P IMPL07 Rep - AP List of Invoice Terms

P APSP76 Rep - Supplier Amendment Journal

P IMPPJC Rep - Currency Amendment Journal

P APSP78 Rep - AP Withholding Tax Report

P Menu + GL Integration

P APSPGI Post - AP Invoice GL Integration

S SRS103 Rep - AP Invoice Journal Report

P APSPGP Post - AP Payments GL Integration

S SRS106 Rep - AP Payment Register

S SRS104 Rep - AP Invoice Expense Distribution

S SRS105 Rep - AP Invoice Disbursement Distribution

P Menu + Setup

P IMPBSP Brows - Suppliers

P IMPBBN Brows - Banks

P IMPBSA Brows - Supplier Classes

P IMPBBS Brows - AP Branches

P IMPBTS Brows - AP Invoice Terms

P IMPBCU Brows - Currencies

P APSPB1 Brows - AP Permanent Entries

P APSPCN Batch - AP Supplier Code Conversion

P APSP90 Brows - AP Initial Invoice Capture

P APSPAR Brows - AP Supplier to Customer Link

P IMPTBH Brows - AP Check Format

P IMPTBC Brows - AP Label Format

P IMPTBX Brows - AP 1099 Label Format

P APSP92 Batch - AP Currency Conversion

P APSP01 Pend - AP Period End

See also

Special files overview


IMPMOD.IMP

SYSPRO SDK

Special Files

IMPMOD.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPMOD.IMP file contains a list of all the standard SYSPRO modules and their description.

This is used by the Company Setup to show a list of licensed modules, in addition the Report Writer and the Data Dictionary system uses this file to determine the pattern matching to use for data files per module.

Defining a Custom file

When SYSPRO programs have completed reading the IMPMOD.IMP file they automatically look for a custom equivalent (CUSMOD.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO information - the operator simply sees a single list. The CUSMOD.IMP file must be in the same format as the standard file. See the sample later in this topic.

Sample IMPMOD.IMP file

This is an example of the first part of an IMPMOD.IMP file.

; IMPMOD.IMP - List of Standard SYSPRO Modules

;

; Copyright (c) 1994-2010 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.1.022 Last updated : 2010/01/05 10:00

;

;Mod Installable Modules

;- ------------------------------

RS Reporting Services

WS Workflow Services

PM Process Modeling

ED Executive Dashboards

IS SYSPRO Interface System

SC Screen Customization Kit

GL General Ledger

AR Accounts Receivable

AP Accounts Payable

CS Cash Book

EF Electronic Funds Transfer

AS Assets Register

CT Contact Management

RW SYSPRO Report Writer

IN Inventory

SO Sales Orders

CO Counter Sales

CR Blanket SO and Releases

RA Return Merchandise

TP Trade Promotions

SA Sales Analysis

PO Purchase Orders

LC Landed Cost Tracking

WM Warehouse Management

QU Quality Management

BM Bill of Materials

AB Activity Based Costing

ES Quotations

PC Product Configurator

WP Work in Progress

FD Factory Documentation

PJ Projects and Contracts

RP Requirements Planning

EC Engineering Change Control

LT Lot Traceability

IF Inventory Forecasting

IG Inventory Families & Groupings

IO Inventory Optimization

PR Preactor Integration

BA Office Automation & Messaging

EN e.net System Manager

DF e.net Document Flow Manager

IA e.net Web-based Applications

A1 SYSPRO Analytics

CM Customer Relationship Manager

FC Finite Capacity Scheduling

FP Factory Planning

PT Progress Tracking

QM Quality Monitoring

;Mod Program prefix modules

;-- ------------------------------

IMP System Admin & Shared Programs

APS Accounts Payable

ARS Accounts Receivable

CSH Cash Book

EFT Electronic Funds Transfer

GEN General Ledger

ASS Assets Register

CMS Contact Management

INV Inventory Control

CFG Product Configurator

POR Purchase Orders

SAL Sales Analysis

WIP Work in Progress

PRJ Projects and Contracts

SOR Sales Orders

RMA Return Merchandise

TPM Trade Promotions

QMS Quality Management System

WMS Warehouse Management System

QOT Quotations

INT Interface System

MRP Material Requirements Planning

BOM Bill of Materials

LOT Lot Traceability

IOP Inventory Optimization

PRE Preactor Integration

REP Report Writer

SRS Reporting Services

SWS Workflow Services

COM Generic Components

DDS Data Dictionary

SDK Software Development Kit

EDI Electronic Data Interchange (Reserved for SYSPRO USA)

;Isam Table

;Mod Data file prefix modules prefix

;-- ------------------------------ -----

ADM System Administration Adm

TBL System Tables Tbl

APS Accounts Payable Ap

ARS Accounts Receivable Ar

CSH Cash Book Csh

EFT Electronic Funds Transfer Eft

GEN General Ledger Gen

ASS Assets Register Asset

CRM Contact Management Crm

INV Inventory Control Inv

CFG Product Configurator Cfg

POR Purchase Orders Por

REQ Requisitions Req

GRN GRN Suspense Grn

LCT Landed Cost Tracking Lct

GTR Goods in Transit Gtr

BPO Blanket Purchase Orders Bpo

SAL Sales Analysis Sal

WIP Work in Progress Wip

PRJ Projects and Contracts Prj

SOR Sales Orders Sor

MDN Multiple Delivery Notes Mdn

POS Counter Sales Pos

BSO Blanket SO and Releases Bso

RMA Return Merchandise Rma

TPM Trade Promotions Tpm

QMS Quality Management System Qms

WMS Warehouse Management System Wms

QOT Quotations Qot

INT Interface System Int

MRP Material Requirements Planning Mrp

STP ST-Point Interface Stp

BOM Bill of Materials Bom

ABC Activity Based Costing Abc

LOT Lot Traceability Lot

IOP Inventory Optimization Iop

ECC Engineering Change Control Ecc

ARC Archive System Arc

REP Report Writer Rep

DDS Data Dictionary Dds

SRS Reporting Services Srs

SWS Workflow Services Sws

Custom CUSMOD.IMP

When developing your own custom applications it is recommended that you use a 3 character prefix for your program development and a 3 character prefix for any data files that you use.

These prefixes should be defined in your custom IMPMOD.IMP called CUSMOD.IMP. This resides in your custom program folder (defined in the System Setup program).

See the following example:

; CUSMOD.IMP - List of Custom SYSPRO Modules

;

; Copyright (c) 1994-2010 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.1.000 Last updated : 2010/01/05 11:30

;

;Mod Program prefix modules

;-- ------------------------------

CUS Custom Development

;Isam Table

;Mod Data file prefix modules prefix

;-- ------------------------------ -----

CUS Custom Development Cus

; End of CUSMOD.IMP

See also

Special files overview


IMPHLP.IMP

SYSPRO SDK

Special Files

IMPHLP.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPHLP.IMP file is used by the SYSPRO Help system to redirect the help topic shown for a program to the text for a different program.

For example the stock code browse is called IMPBST. The help file name for this browse is called impbst.htm. However this help file also contains details of the Stock code maintenance program (IMP030). Therefore the help for the program IMP030 is actually defined in impbst.htm. The IMPHLP.IMP file is used to redirect the help for IMP030 to impbst.htm.

Note that only programs that need this 'help file redirection' need an entry in IMPHLP.IMP.

In the above example the help file loaded will be base\htmlhelp\impbst.htm

Defining a Custom file

When the SYSPRO help system has completed reading the IMPHLP.IMP file it automatically looks for a custom equivalent (CUSHLP.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO information. The CUSHLP.IMP file must be in the same format as the standard file.

There is no limit to the number of entries.

Sample IMPHLP.IMP file

Note that the format of this file has changed from SYSPRO 6.0 issue 009 onwards. To see an example of the older file format see the example at the end of this topic.

; IMPHLP.IMP - SYSPRO 6.0 SYSPRO Help Redirector

;

; Copyright (c) 1994-2004 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.0.000 Last updated : CCYY/MM/DD HH:MM

;

; Col Usage Notes

; ----- --------------------------------- ---------------------------

; 1-6 Program name (lowercase) 6 characters, ';' - Comment

; 9-11 Source context number 'all' matches all else 001-999

; 13-42 Redirect to URL (lowercase) Appended to base\htmlhelp

[HelpBody]

Program Num URL

------ --- ------------------------------

imp030 all impbst.htm

Showing CHM help content

Apart from redirecting the help for one program to show the help for another program you can also direct the help for your custom program to show help in a CHM format file.

CHM files are a common format for help content.

To redirect your custom program (e.g. CUST10) to show a help file called CUSTOM.CHM you can add the following line to a file called CUSHLP.IMP stored in the custom program directory.

; CUSHLP.IMP - SYSPRO 6.0 Custom Help Redirector

;

[HelpBody]

Program Num URL

------ --- ------------------------------

cust10 all chm:custom.chm ;Call CUSTOM.CHM

SYSPRO 6.0 issue 008 and prior format IMPHLP.IMP file

This is an example of the first part of an IMPHLP.IMP file from SYSPRO 6.0 issue 008 and earlier.

This IMPHLP.IMP file contains a cross-reference between the standard SYSPRO programs and the help file and topic number that should be shown when the operator presses F1 in the program.

6.0 Help context cross-reference file

------------------------------------------

@(#) Version : 6.0.005 Last updated: CCYY/MM/DD

Copyright (c) 1994-2003 SYSPRO Ltd. All rights reserved.

Column Usage

------ ----------------------------------------

1-6 Name of program where F1 pressed

8-10 Section of program/screenset (If 'all' indicates all

sections have same help)

12-17 Name of .HLP file containing help text

19-22 Context to be shown in .HLP file

Prog Sec .HLP Context

Report Writer

REPPB4 all REPPAC 10

REPPZ1 all REPPAC 15

REPPZ2 all REPPAC 20

REPP80 all REPPAC 25

REPP90 all REPPAC 30

REPPB1 all REPPAC 35

REPPB2 all REPPAC 40

REPPB3 all REPPAC 45

REPP72 all REPPAC 50

REPP73 all REPPAC 55

REPP74 all REPPAC 60

REPP75 all REPPAC 10

REPP77 all REPPAC 70

See also

Special files overview


IMPMSG.IMP

SYSPRO SDK

Special Files

IMPMSG.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPMSG.IMP file contains a list of many common messages used by the system.

The function LOOK-UP-ERROR that is used to extract the appropriate message from this file. Each message is identified by the record number in the file and therefore you should not edit this file. See the function description for more details and a worked example.

Note that this file was named IMPACT.ERR prior to SYSPRO 6.1.

Sample IMPMSG.IMP file

This is an example of the first part of an IMPMSG.IMP file.

@#! SYSPRO Message File @(#) Last updated 24th Nov 2009 Version 6.1.000

Not on file.

Locked by another user.

Already on file.

Incorrect password.

Attempting to open a file

Attempting to read a record

Attempting to write a record

Attempting to update a record

Attempting to delete a record

Reading a tag-file

Account is on hold

File does not exist

Attempting to read next record

Attempting to read previous record

See also

Special files overview


IMPPRT.IMP

SYSPRO SDK

Special Files

IMPPRT.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPPRT.IMP file contains a library of common printer definitions to be used when adding a non-Windows printer.

Defining a Custom file

When adding a non-Windows and the printer maintenance program has completed reading the IMPPRT.IMP file it will automatically look for a custom equivalent (CUSPRT.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO information - the operator simply sees a single list. The CUSPRT.IMP file must be in the same format as the standard file.

Sample IMPPRT.IMP file

This is an example of the first part of an IMPPRT.IMP file.

List of printers in SYSPRO

Copyright (c) 1994-2003 SYSPRO Ltd. All rights reserved.

@(#) Version : 6.0.001 Last updated CCYY/MM/DD HH:MM

To translate the wording in this file, copy this file to your

system-wide screenset directory, and modify it there.

Prt = Printer name (Max 30)

Rpd = Description of a report attribute (Max 30)

Fld = Description of a field attribute (Max 30)

On = Start of attribute (in hex code)

Off = End of attribute (in hex code)

Prt: HP Laserjet IIP

Rpd: Courier (10 point)

On : 1B2838551B28733070313068313276307330623354

Off:

Rpd: Courier Bold (10 point)

On : 1B2838551B28733070313068313276307333623354

Off:

Rpd: Courier Italic (10 point)

On : 1B2838551B28733070313068313276317330623354

Off:

Rpd: Courier (12 point)

On : 1B2838551B28733070313268313276307330623354

Off:

Rpd: Compressed (8.5 point)

On : 1B2838551B2873307031362E363668382E3576307330623054

Off:

Fld: Courier (10 point)

On : 1B2838551B28733070313068313276307330623354

Off:

Fld: Courier Bold (10 point)

On : 1B2838551B28733070313068313276307333623354

Off:

Fld: Courier Italic (10 point)

On : 1B2838551B28733070313068313276317330623354

Off:

Fld: Courier (12 point)

On : 1B2838551B28733070313268313276307330623354

Off:

Fld: Compressed (8.5 point)

On : 1B2838551B2873307031362E363668382E3576307330623054

Off:

Fld: Barcode 3of9 (cart) 8.1 CPI

On : 1B2830591B28733070382E31683132763073306230542A

Off: 2A1B283855

Fld: Barcode 3of9 (cart) 4.6 CPI

On : 1B2830591B28733070342E36683132763073306230542A

Off: 2A1B283855

Fld: Opt.char.(cart) 10 CPI (OCR-A)

On : 1B28304F1B7330703130683132763073306231303454

Off: 1B283855

Fld: Opt.char.(cart) 10 CPI (OCR-B)

On : 1B28314F1B7330703130683132763073306231313054

Off: 1B283855

See also

Special files overview


IMPPSS.IMP

SYSPRO SDK

Special Files

IMPPSS.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPPSS.IMP file contains a list of program functions that can be protected by password.

Each program function is assigned a 6 character name - each name begins with '-', for example '-ADM01' is the 'Admin factory calendar maintenance' function.

The Setup, Security, Password program uses this list to provide a user-interface for the system administrator to be able to set and clear these passwords.

The passwords are stored in the Generic password system.

Programs can easily request and verify these passwords without having to provide any user-interface. See the ASK-PASSWORD and S-PASSASK functions.

Defining a Custom file

When SYSPRO programs have completed reading the IMPPSS.IMP file they automatically look for a custom equivalent (CUSPSS.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO information - the administrator simply sees a single list of passwords. The CUSPSS.IMP file must be in the same format as the standard file.

Sample IMPPSS.IMP file

This is an example of the first part of an IMPPSS.IMP file.

; IMPPSS.IMP - Password Definitions

;

; Copyright (c) 1994-2004 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.0.000 Last updated : 2004/05/24 12:00

;

; Col Usage Notes

; ----- --------------------------------- ---------------------------

; 1-6 Password Type 6 character password type

; 7-17 Filler for future use 10 spare characters

; 18-78 Description 70 character description

;

; Type Description

; ------ ----------------------------------------------------------------------

;Mod ADM System Administration

-ADM01 Admin factory calendar maintenance

;Mod APS Accounts Payable

-APS01 A/P Posting to a previous month

-APS02 A/P Entry of GRN matching value exceeding allowed GRN variance

-APS03 A/P Override on expected costs percentage variance (LCT system)

-APS04 A/P Maintenance of credit management notes

;Mod ARS Accounts Receivable

-ARS01 A/R Posting to a previous month

-ARS02 A/R Viewing of customer profits in customer query

-ARS03 A/R Maintenance of credit management notes

-ARS04 A/R Posting a payment in Payment and Adjustments

-ARS05 A/R Posting an adjustment in Payments and Adjustments

-ARS06 A/R Maintaining an invoice in the Invoice browse

-ARS07 A/R Deletion of customers

-ARS08 A/R Re-establishing of invoices

See also

Special files overview, Generic password system, ASK-PASSWORD, S-PASSASK


IMPSEC.IMP

SYSPRO SDK

Special Files

IMPSEC.IMP Definition

Introduction

When SYSPRO is installed various text files are shipped as part of the product. These files are used by various programs as the source of their information.

The IMPSEC.IMP file contains a list of standard SYSPRO Activities and Fields that can be protected at the operator code level (and Role level from SYSPRO 6.1)

The maintenance programs use the IMPSEC.IMP to provide a list of Activities and Fields that may be protected.

Note that the Activities and Fields will be shown in the sequence that they appear in the IMPSEC.IMP file. However each Activity/Field setting references a table of 200 flags. The first 3 columns in the IMPSEC.IMP file identify the subscript in to this table of 200 flags. When adding new Activity/Fields you should insert the new line in the position where you want it to appear and then you must ensure that the subscript is the next available subscript.

Defining a Custom file

When SYSPRO programs have completed reading the IMPSEC.IMP file they automatically look for a custom equivalent (CUSSEC.IMP) in the custom program directory. If this file is found the information is appended to the standard SYSPRO information - the operator simply sees a single list. The CUSSEC.IMP file must be in the same format as the standard file.

Sample IMPSEC.IMP file

This is an example of an IMPSEC.IMP file.

; IMPSEC.IMP - List of Security Access Activities and Fields

;

; Copyright (c) 1994-2003 SYSPRO Ltd. All rights reserved.

;

; @(#) Version : 6.0.027 Last updated : CCYY/MM/DD HH:MM

;

; Col Usage Notes

; ----- --------------------------------- ---------------------------

; 1-3 Subscript 3 characters, ';' - Comment

; the fields will be displayed in

; the sequence listed in this file

; 8-37 Description 40 character description

;

; 200 activities available, 180 - 200 reserved for user defined activities

; highest current subscript - 083

;

; 200 fields available

; highest current subscript - 023

;

;Sub Description

;--- ----------------------------------------

[Activities]

001 Stock receipts

002 Stock adjustments

003 Stock cost changes

004 Cost modifications

005 Backflushing

006 Warehouse transfers

007 Bin transfers

008 Physical count

009 Expense issues

010 A/R Invoices

011 A/R Credit notes

012 A/R Debit notes

013 A/R Payments

014 A/R Adjustments

015 A/R Misc. receipts

016 S/O Orders

017 S/O Billing

018 S/O Scheduled order

019 S/O Credit note

020 S/O Debit note

021 S/O Forward order

022 S/O Counter sales

023 S/O I.B.T.

024 S/O Hierarchical order

025 S/O Print delivery note

026 S/O Print acknowledgement

027 S/O Print invoice

028 S/O Print credit note

029 S/O Print debit note

030 A/P Invoices

031 A/P Credit notes

032 A/P Debit notes

033 A/P Adjustments

034 A/P Register invoice

035 A/P Approve invoices

036 A/P Contra invoices

037 C/B Deposits

038 C/B Withdrawals

039 P/O Print purchase order

040 A/P LCT register invoice

041 View Structure & Routings

042 S/O Print Dispatch Note

043 S/O Print Dispatch Inv

044 Stock Code on Hold

045 Change Ship Qty on hold

046 P/O Inspection functions

047 S/O Supply Chain Transfer

048 S/O Print SCT transfer

049 S/O Mark order complete

050 S/O Print quick quote online

051 S/O Copy - change codes

052 S/O Show cost/profit

053 Custom form maintenance

;

[Fields]

001 A/R Credit limit

002 A/R Credit terms

003 Text Technical spec

004 Text Sales order

005 Text Purchase order

006 Text Job narrations

007 Text Inspections

008 Text Dangerous goods

009 Show costs in Inventory/WIP queries

010 Show costs in Stock Code maintenance

;

; End of IMPSEC.IMP

See also

Special files overview


IMPACT.INI

SYSPRO SDK

Special Files

IMPACT.INI Definition

Introduction

This topic covers the purpose, structure and contents of the SYSPRO IMPACT.INI file.

When SYSPRO is installed the Setup program creates an IMPACT.INI file in the work directory. This text file contains various settings and paths that are used by SYSPRO as basic system wide information. This file can be maintained using the System Setup program from the main menu pull down.

The IMPACT.INI file is divided into 5 sections. These are:

  • System Settings

  • Standard Directories

  • Custom Directories

  • Data Directories

  • Database Settings

A sample IMPACT.INI file for a C-ISAM based system is shown below:

[System Settings]

IMPDAT=MMDDYY

IMPNAT=USA

IMPUSR=0016

IMPDEV=

IMPSDT=MM/dd/yyyy

IMPLDT=dddd D MMMM yyyy

IMPRDT=dddd D MMMM yyyy HH:mm

IMPLGN=NETWORK

[Standard Directories]

IMPPRG=C:\Program Files\Syspro\Programs

IMPGUI=C:\Program Files\Syspro\Screens

IMPTMP=C:\Program Files\Syspro\Temp

[Custom Directories]

CUSPRG=C:\Program Files\Syspro\CusProg

CUSGUI=C:\Program Files\Syspro\CusScrn

[Data Directories]

IMPDT1=C:\Program Files\Syspro\Data

IMPSNP=C:\Program Files\Syspro\Snapshot

[Database Settings]

SQLSYS=ISAM

How IMPACT.INI is used by SYSPRO Programs

The SYSPRO login process reads the IMPACT.INI file when an operator log’s in and loads the various settings into a common memory area (called a linkage defined by LINK.WRK) that is available to all SYSPRO programs.

In addition many of these parameters are passed to the SYSPRO library function program (IMPSTD). For example when a program wishes to open a data file it uses a library function to build the file name. This uses the setting in the IMPACT.INI to build the appropriate path.

In addition to the main Setup program having created the IMPACT.INI file initially, these settings can be maintained at any time using the System Setup program that is available from the SYSPRO menu pull down.

Note that in a Client/Server environment there is an IMPACT.INI file on both the Server and Client systems. These files are used to configure both the Client and Server. For example the Client’s IMPACT.INI defines the screenset directory, whilst the Server’s IMPACT.INI defines the program and data directories. Also, depending on the Client’s configuration, there may be several Client IMPACT.INI files. It is possible for each Client to use it’s own IMPACT.INI.

In all cases if an entry does not exist a default will be provided.

The System Setup program allows you to edit the IMPACT.INI on the server. In addition since SYSPRO 6.0 issue 007 there is also a push button 'Edit Client IMPACT.INI' that allows you to edit the Client's IMPACT.INI. Note that there are only a few settings that are used for the Client's IMPACT.INI.

Structure of IMPACT.INI

IMPACT.INI is an ASCII file stored in a format editable by most text editors such as NOTEPAD on Windows or vi under Unix.

There are various sections that are identified by tags. A tags is simply a text description surrounded by square brackets. For example:

[System Settings]

The parameters immediately following a tag belong to the section.

To temporarily comment out an entry you can prefix the line with a semi-colon (;).

All entries consist of a six character parameter followed by an equal sign (=) followed by the parameter’s value. For example:

IMPDAT=MMDDYY

Where IMPDAT is the parameter and MMDDYY is the value.

If a parameter is missing then a default value will be supplied.

A parameter must only appear once per IMPACT.INI file.

The parameters themselves are not case sensitive but their values are case sensitive.

The following section contains a complete definition of each available parameter together with a sample value.

IMPACT.INI Settings

This is a complete definition of all current IMPACT.INI settings. The last 3 columns define whether the setting is valid on the given environment. The columns are:

  • M - IMPACT.INI in the working directory of a standalone/mapped drive system

  • S - IMPACT.INI in the Server’s working directory in a Client/Server environment

  • C - IMPACT.INI in the Client’s working directory in a Client/Server environment.
    (Note there can be many of these depending on the Client PC’s configuration)

Variable

Example Value

Description

M

S

C

[System Settings]

IMPDEV

TESTGS

Production/Development system indicator

Valid settings are:

{Blank} – Normal production system. If the IMPDEV= entry does not exist this is the default setting.

TESTRS – Dev system using RS files

TESTGS – Dev system using GS files

ON – Special Dev system (uses GS files). This entry must only be used in SYSPRO’s internal development environment and may fail unexpectedly outside of SYSPRO. Third party developers must not use this value.

Y

Y

Y

IMPDAT

MMDDYY

Date presentation format for screens and reports

Valid options are:

DDMMYY – dd/mm/yy

MMDDYY – mm/dd/yy

YYMMDD – yy/mm/dd

Y

Y

IMPNAT

USA

Nationality code

A 3 character code that is used for various defaults and tax settings

From SYSPRO 6.0 issue 006 you can specify this setting at the company level.

Y

Y

IMPUSR

0016

Number of licensed concurrent users

A 4 digit setting that must match your licensed information (was 3 digits prior to SYSPRO 6.1)

Y

Y

IMPCMO

0010

Number of Contact Management Only users

A 4 digit number of concurrent users that can only access SYSPRO Contact Management System features. SYSPRO 6.1 onwards

Y

Y

IMPODB

002

Number of licensed ODBC seats

A 3 digit setting that must match your licensed information

Y

Y

IMPUSQ

000

Number of licensed U/SQL seats

A 3 digit setting that must match your licensed information

Y

Y

IMPDSG

000

Number of Dialog System seats

A 3 digit setting that must match your licensed information

Y

Y

IMPCAL

000

Number of Microsoft SQL Server Client Access Licenses (CAL) seats

A 3 digit setting that must match your licensed information

Y

Y

IMPSIT

Site01

Site code

A 6 character documentary field

Shown in the System information program

Y

Y

IMPCOM

sql01

Diagnostic field

A 6 character documentary field

Used for debugging and logging

Y

Y

IMPSDT

MM/dd/yyyy

Short date format

This is a 50 character field that can be used to format a short date

The Short date can be used in stationery documents and the Report Writer

Y

Y

IMPLDT

dddd D MMMM yyyy

Long date format

This is a 50 character field that can be used to format a long date

The Long date can be used in stationery documents and the Report Writer

Y

Y

IMPRDT

Dddd D MMMM yyyy HH:mm

Report date format

This is a 50 character field that will be used to format a date in the majority of report headings

Y

Y

IMPLGN

NETWORK

Default login lookup

Valid setting are:

NETWORK – use the network user name to lookup the operator code. This must be valid unless IMPOPR=OVERRIDE is defined in which case the Network user name will be requested.

OPERATOR – use the environment variable %LOGIN to read the operator code. This must be valid unless IMPOPR=OVERRIDE is defined in which case the Operator code will be requested.

Y

Y

IMPOPR

OVERRIDE

Allow the operator code/network user name to be entered/changed at login time

Valid settings are:

OVERRIDE – allow entry/override

{Blank} – No override allowed

Y

Y

IMPWRI

Third party report writer executable name

Y

Y

IMPSTR

Third party report writer start in directory

A 255 character start in directory. It can contain spaces.

Y

Y

IMPREP

Third party report writer description

Y

Y

[Standard Directories]

IMPPRG

C:\Syspro\Programs

Standard program directory

A 255 character path to the standard SYSPRO programs. It can contain spaces for example

C:\Program Files\Syspro\Programs

Y

Y

IMPGUI

C:\Syspro\Screens

Standard screenset directory

A 255 character path to the standard SYSPRO screensets. It can contain spaces.

On a Client/Server system on the Server this defines the latest screensets ready to be transferred to the client.

On a Client/Server system on the Client this defines the current screenset directory

Y

Y

Y

IMPTMP

C:\Syspro\Temp

Temporary directory

A 255 character path to the temporary directory. It can contain spaces.

This is only used if there is no TEMP environment variable defined

Y

Y

Y

IMPMCI

C:\Syspro\Media

Multimedia directory

A 255 character path to the default multimedia directory. It can contain spaces.

On a Client/Server system this is used on the Client side only

Y

Y

IMPSTP

C:\Syspro\Aps

APS interface directory

Y

Y

[Custom Directories]

CUSPRG

C:\Syspro\CusProg

Custom program directory

A 255 character path to any custom programs. It can contain spaces

Y

Y

CUSGUI

C:\Syspro\CusScrn

Custom screenset directory

A 255 character path to any custom SYSPRO screensets. It can contain spaces.

On a Client/Server system on the Server this defines the latest custom screensets ready to be transferred to the client.

On a Client/Server system on the Client this defines the current custom screenset directory

Y

Y

Y

[Data Directories]

IMPDT1

C:\Syspro\Data

Data directory

A 255 character path to the data directory. It can contain spaces

You can define up to 9 data directories (IMPDT1 – IMPDT9) and split companies or individual files between these directories

Y

Y

IMPSNP

C:\Syspro\Snapshot

Snapshot directory

A 255 character path to the snapshot directory. It can contain spaces.

This is used by MRP to contain a snapshot of live data files

Y

Y

[Database Settings]

SQLSYS

SQLSERVER

Database or ISAM setting

Valid entries are:

ISAM – All files are C-ISAM

SQLSERVER – At least one company uses MS SQL Server

Y

Y

SQLLGN

OPERATOR

Database login method

Valid entries are:

OPERATOR – use the SQL login defined against the operator code

NT – Use NT Authentication

Y

Y

SQLDSN

SysproServer

Data Source Name

A 20 character ODBC data source name.

Y

Y

SQLDBN

Sysprodb

Configuration data base name

A 20 character configuration data base name.

Y

Y

SQLTBN

SysproAdmin

Configuration table name

A 20 character configuration table name.

Y

Y

Note that the on-line help available in the System Setup program identifies the IMPACT.INI entry that the option represents.

See also

Special files overview


CUSTOM.IMP

SYSPRO SDK

Special Files

CUSTOM.IMP Definition

Introduction

The CUSTOM.IMP file should be used to define all your customized programs. It should be defined in your working directory (on the server in a client/server system). This file can be edited with any text editor (such as NOTEPAD on Windows or vi on Unix).

The entries in the file are prefixed by a code that identifies whether the programs can be run by everyone (system-wide), or only for certain companies, groups or operators.

In addition it is possible to redirect a standard program to a customized program. For example if you wish to deploy a customized version of the Stock Code browse (INVBST) you can inform SYSPRO that every time INVBST runs it should call CUSBST instead.

Note that the CUSTOM.IMP file is read when you log into SYSPRO - so if you make changes you must log out for these to take effect.

It is recommended that you add comments (prefixed with ;) to assist in later identification.

See the following example

; CUSTOM.IMP

; Code Prog Program ;Comment (must be prefixed by ;)

; ------ ------ ------ ----------------------------------------------

A CUSBST INVBST ;Run CUSBST instead of INVBST for all users

A CUSP10 ;CUSP01 is a custom program for all users

C 1 CUSPEN ;CUSPEN is a custom program in company 1

G ADMIN CUSP01 ;CUSP01 is a custom program for users

; ;belonging to group ADMIN

O USER CUSP20 ;CUSP20 is a custom program for operator 'USER'

Note that CUSTOM.IMP file is only used when the company has the Screen Customization Kit module installed.

See also

Special files overview, Deploying custom programs


Password System

Introduction

The SYSPRO password system is designed to:

  • Provide a common and consistent way of defining and verifying passwords

  • Provide a common interface to the operator

  • Provide password encryption for improved security

  • Provide improved operator password security by including the following features

    • allow operators to be able to change their own passwords

    • allow an expiry period to ensure passwords are changed

    • using password rules to prevent easily 'guessable' passwords being defined,

    • storing a list of previously defined passwords to prevent 2 or more passwords being recycled

    • Providing a supervisor password that can be entered at any time that an operator password is requested.

  • Provide an operator lockout function

  • Provide an open architecture so that future passwords in standard SYSPRO programs and third party developers can use this system.

Types of password usage in SYSPRO

There are several types of passwords used in SYSPRO. These have slight differences but can all use the new password system.

Please note that the Operator and Company passwords were the first passwords in SYSPRO to use this mechanism - these were implemented in Encore 5.0. Subsequently the Report Writer (Report Maintenance and Report Writer) passwords were added. Since SYSPRO 6.0 issue 009 all program function passwords (such as preventing entry of a credit note) have been converted to use the password system.

Password against an Operator

This is a very important password in SYSPRO as the operator is used to determine many security settings. These include the program security (via the operator group), which menus are available and which companies, warehouses, branches, salespersons etc can be accessed.

Operator password configuration is explained later in this document

Password against items such as G/L codes

There are a few types of items in SYSPRO that allow definition of a password. Before an operator can use one of these codes the password must be verified. An operator who has permission to maintain an item will be able to change the password (after all they can delete the item!). This includes the Company password and Ledger code password.

Password against program functions

There are a large number of miscellaneous functions that can be password protected in SYSPRO. For example this includes the ability to prevent processing of a credit note.

These passwords are maintained from a central password setup program - use Setup, Security, Passwords from the main SYSPRO menu.

Since issue 009 these program function passwords have been incorporated into the generic password system. The file IMPPSS.IMP defines each password together with the internal 6 character codes associated with each password.

Operator Passwords

Due to the importance of the Operator code in SYSPRO there are several password features that have been designed to enable the System Administrator to configure the system for the required level of security.

An administrator (the operator must belong to an administrator group) can setup the operator password configuration using one of two methods.

  1. Load the Setup, Security, Passwords… program from the main menu and click on the Operator Setup… push button

  2. Load the Setup, Security, Operators… program from the main menu and select Configure, Password Setup…

    This will display a dialog box similar to the one below:

Allowing Operators to Change their Own Passwords

The Administrator can configure whether operators can change their own passwords.

Until this feature was provided the administrator has been responsible for maintaining all operator passwords. However the continual passing of these 'administrator-defined' passwords is tedious for the administrator (and therefore tends not to get done as often as it should) and is a security leak in itself.

However once you allow operators to set their own passwords a number of parameters are required to ensure the integrity of the system. These include:

  • An expiry interval must be defined to ensure that operators change their passwords frequently enough. A numbers of days (default of 14 but configurable) before a password is due to expire the operator will be warned when they log into SYSPRO and given the option of changing it. This warning will count down each day until the expiry date is reached or a new password is defined. If the password expires then only an administrator can reset the operator's password and thus re-enable the operator code. Note that administrator passwords never expire.

  • A minimum password length should be defined. For example entering a one, two or three character password is just not secure enough. At least 4 characters is recommended.

  • Forcing at least one digit in the password. This facility is often used to encourage the operator to not use regular words as passwords. It's much more difficult for someone trying to guess a password when at least one of the characters is a numeric digit.

  • Retaining a history of previously entered passwords for each operator. This is required as many operators, once forced to define new passwords on a regular basis, tend to re-use a number of passwords repeatedly. For example by entering the password 'day' and later changing it to 'night' and then next time using 'day' again. The password history is retained in an encrypted format. The administrator can configure the number of entries in the password history file per person. In addition the password history may be reset.

Supervisor password

The administrator can optionally configure a supervisor password. This password can be entered whenever any operator password is requested.

Uses of the supervisor password include:

  • Gaining access to an operators account when they are not available or if they have forgotten their password

  • As protection against forgetting the regular administrator password.

It is vitally important that, if defined, the supervisor password is kept secure.

The supervisor password can be disabled by un-checking the option Supervisor password required

Operator lockout function

There is a function that allows the administrator to lock out an operator. This can be useful where an operator is not in the office for an extended period and you want to ensure that no one uses this operator code.

This lock out flag can be set/reset using the operator maintenance, Security tab.

Note that when an administrator uses the operator password configuration option to force a new password at next login the system will automatically lock out any operator without a password.

Developers Interface to the Password System

This section is aimed at developers creating new systems or applying security against existing facilities.

All the password functions are available from your source code using PERFORM's in PROBEGIN.PRO in addition they can be called directly from a screenset using standard dialog functions.

The password functions available are

Asking a password

This function is used to show a simple dialog box that requests a password. This password will not be echoed. The password will be verified against the existing password and a status will be returned indicating whether the password was entered successfully.

See the functions ASK-PASSWORD and S-PASSASK

Verifying a Password

This function is used when the program has requested a password itself (an example of this is on the main SYSPRO Login screen where it makes sense to ask the password on the same dialog box as the operator and company prompts). The entered password is passed to the function and the program will return a status indicating whether the password was entered successfully.

See the functions VERIFY-PASSWORD and S-PASSVER

Setting a Password

This function is called whenever a new password is to be set using the password system. If there is an existing password then this will be requested (and must be valid) before entering and reconfirming the new password. The new password will be encrypted and stored in the password system.

See the functions SET-PASSWORD and S-PASSSET

  • There is a function to allow setting of the password without forcing entry of any pre-existing password. This is used when the operator (often an administrator) requires to set passwords. See SET-PASSWORD-NO-OLD

  • There is a function to allow the program to set a password without asking any questions. This can be used where your program provides the user-interface to ask the new password and you just want to set it. See SET-PASSWORD-NO-ASK. This is also useful when adding a number of passwords automatically - for example when converting from an older password system.

Getting Password Info

This function allows a program to find out whether there is an existing password for a given item. This can be used to determine whether there is a password so that the ‘Ask Password’ function can be requested or to determine whether a ‘Password:’ entry field should be enabled/disabled.

See the functions GET-PASSWORD-INFO and S-PASSINFO

Adding a Password Control Record

This function allows you to add a control record to the password system. The control record is required before you can define your own types of passwords. This only needs to be done once at each end-users site.

See the functions ADD-PASSWORD-CTL and S-PASSCTL

Deleting an existing Password

This function allows you to delete a password against an existing item. This is generally used when deleting a key item. No user-interface is provided.

See the function DEL-PASSWORD

Password Encryption

The system will accept passwords consisting of any 30 characters. These will be encrypted using a proprietary one-way algorithm and will be stored in a password file. The encryption will incorporate the entered 'plain text' password, type of password, key of the item and the expiry date (for operators). This means that even if the same password is used for various items or types of items a unique encrypted code will be generated.

For example even if two operators enter the same 'plain text' password the encryption will differ.

Password Verification

When a password is to be verified the proposed 'plain text' password together with the type and key of the item will be passed to a function. This function will encrypt the password using the algorithm and it will be compared with the encrypted password 'on file'. If the password verification fails the system will wait for the next second to elapse on the computer (the maximum delay is just under 1 second) . This small delay when an invalid password is entered means that a brute force approach to cracking a password is out of the question. For normal usage the operator will not notice this (especially if they enter the password correctly as there is then no delay at all).

Forcing change of password

There are two functions that allow you to set/clear the flag forcing an operator to change their password at next login.

See the functions SET-FORCE-CHANGE-PASSWORD and CLEAR-FORCE-CHANGE-PASSWORD

How do I use these password functions?

As mentioned previously there are two main types of password. One where the password is defined against a key field (such as an operator, report or ledger code) and another where the password protects a function (such as changing a price against a Sales Order line).

The password system uses two fields as a unique identifier for the item being protected. The first field is a password type - this is a 6 character field identifying the type of password. The second field is the key of the item being protected - this is a 90 character key field.

Key field passwords

In the case where a key field is to be protected then the first field often contains the name of the file being protected, but can be any 6 character code. For example the operator password uses 'ADMOPR' as the 6 character password type. See the record layout ADMPAS.MAI for a list of currently used password types.

The second field is simply the key of the item being protected. In the case of the operator password this is the operator code.

It is recommended that developers use 6 character codes that start 'USR' to avoid possible future conflict with standard SYSPRO passwords.

Program function passwords

In the case of program functions (such as changing a price against a Sales Order line) the program types are defined by a 6 character code starting with '-'.

For example '-SOR03' is used to protect the 'S/Order Changing prices' function.

The list of program functions is defined in the file IMPPSS.IMP. The maintenance of the passwords defined in this file is performed using the Setup, Security, Passwords program from the SYSPRO main menu.

Note that developers can provide a custom version of this file (CUSPSS.IMP) in the custom program directory. These can then be maintained by the same Setup, Security, Passwords program as is used for standard SYSPRO passwords. It is recommended that custom password functions begin '-USR' - for example '-USR01'.

Note that for program function passwords the key field should be spaces.

Example code to request the password protecting the function to change the price on a Sales Order line (code '-SOR03').

MOVE SPACES TO LINK-PASS.

MOVE "-SOR03" TO LINK-PASS-TYPE.

PERFORM ASK-PASSWORD.

IF LINK-PASS-OK NOT = SPACES

MOVE SPACES TO LINK-PASS

GO TO INVALID-PASSWORD.

Note that the linkage fields should be initialized before used. This is achieved by using - MOVE SPACES TO LINK-PASS. Generally this field should also be cleared after use as it redefines the generic field LINK-EXTRA.

Invoking the password functions from a screenset

The majority of the password functions can also be invoked directly from a screenset without having to use any source code.

For example to ask the same password in the dialog system use:

MOVE "S-PASSASK" S-FR-MSG

MOVE "-SOR03" S-FR-PAR

RETC

IFNOT= S-ERROR " " INVALID-PASSWORD-PROC

See also

ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-OLD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD

and

S-PASSASK, S-PASSSET, S-PASSSETN, S-PASSVER, S-PASSINFO, S-PASSCTL


Custom Forms

Introduction

The Custom Forms system consists of a set of functions that allow end-user defined forms to be created and edited. It is simple for a developer to add a custom forms capability to a key field.

The following functions are provided:

Source code | Dialog | Notes
CUSTOM-FORM-EDIT | S-FORM-EDT | Add and maintain data in a custom form
CUSTOM-FORM-GET | S-FORM-GET | Retrieve single value of custom form data
CUSTOM-FORM-DEL | S-FORM-DEL | Delete a custom form for a key field
CUSTOM-FORM-TEST | S-FORM-TST | Test custom form for mandatory fields
CUSTOM-FORM-COPY |  | Copy custom form data to another key field
CUSTOM-FORM-COPY-TYPE |  | Copy custom form data to another form type
CUSTOM-FORM-READ-ALL |  | Retrieve all values for a custom form
CUSTOM-FORM-READ-CTL |  | Retrieve names of fields in a custom form

Custom forms

When maintaining a key field, such as a customer, supplier, job or sales order, it may be required that the operator enter or maintain one or more fields not supplied as standard in SYSPRO. The Custom form system allows a System implementor or System Administrator to configure a custom form for a key type (customer, supplier, job, sales order etc).

The custom form can contain one or more fields of user-defined configuration.

Custom form types

Custom forms have been defined as standard against various key fields in SYSPRO. Each custom form type is assigned a 6 character code. The custom form functions require the 6 character form type to ensure that the appropriate custom form data is accessed.

Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

See also

CUSTOM-FORM-EDIT, CUSTOM-FORM-GET, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST

and

S-FORM-EDT, S-FORM-GET, S-FORM-DEL, S-FORM-TST


Multimedia

Introduction

The generic multimedia system consists of a set of functions that allow end-user defined multimedia objects such as bitmaps, sound clips, videos and other OLE2 objects to be linked to a key field. It is simple for a developer to add a multimedia capability to a key field.

The following functions are provided:

Source code | Dialog | Notes
MULTIMEDIA-PLAY | S-MPLAY | Play/show multimedia objects against a key field
 | S-MEDIT | Allow operator to link multimedia objects to a key field
MULTIMEDIA-DELETE-ALL | S-MDEL | Delete all multimedia objects for a key field
MULTIMEDIA-GET-PATH | S-MPATH | Get path of multimedia object

Multimedia

When maintaining a key field, such as a customer, supplier, job or sales order, it may be required to link objects such as bitmaps, sound clips, video clips or other OLE2 objects to a key field.

There are many way that this could be used - for example a map of the customers location could be linked to a customer.

Multimedia types

The Multimedia facility has been defined as standard against various key fields in SYSPRO. Each multimedia type is assigned a 6 character code. The multimedia functions require the 6 character type to ensure that the appropriate object's data is accessed.

Existing multimedia types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own multimedia objects should use key types beginning with USR.

See the record layout ADMMMA.MAC for a complete list of multimedia types.

See also

MULTIMEDIA-PLAY, MULTIMEDIA-DELETE-ALL, MULTIMEDIA-GET-PATH, S-MPLAY, S-MEDIT, S-MDEL, S-MPATH


Notepad

Introduction

The generic notepad system consists of a set of functions that allow end-user defined notes to be linked to a key field. It is simple for a developer to add a notepad capability to a key field.

Most functions are available from within a screenset using standard dialog functions. In addition some extra functions are available from a source program.

The following functions are provided:

S-NEDIT | Allows an operator to add/view/edit notes against a key field
S-NTEST | Tests if notes have been defined against a key field
S-NDEL | Deletes notes against a key field
S-NGRTF | Retrieve RTF filename
S-NMOVE | Move notes from one key field to another (where codes are renamed)
S-NVIEW | Allows operator to view but not edit notes
S-NCOPY | Allows notes to be copied from one item to another

Notes

There are many way that this could be used - for example notes against a stock code could be retained for later viewing.

Note types

The Notepad facility has been defined as standard against various key fields in SYSPRO. Each notepad type is assigned a 6 character code. The notepad functions require the 6 character type to ensure that the appropriate object's data is accessed.

Existing notepad types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own notepad objects should use key types beginning with USR.

See the record layout ADMNOT.MAI for a complete list of standard notepad types.

Additional functions

Some functions requiring potentially large amounts of data can only be called from a program - there is no equivalent dialog system function. These are detailed below.

Retrieving text without formatting characters

When using the generic notepad the operator can use a variety of attributes to format the text effectively. These include Bold, Italic, Underline, Left, Center, Right justification and Font selection.

You may occasionally want to extract 'just the text' for display or print purposes. This can be done from a program by passing the maximum length of line (in characters). The notepad program will return a string of characters without any formatting characters split into these line lengths.

In the following example we require to extract notes for a ledger code '001000' and require the notes formatted a maximum 60 characters per line.

* Allow for up to 200 lines

01 LNK2 PIC X(32000).

01 TEXT-TABLE REDEFINED LNK2.

03 TEXT-TAB OCCURS 200.

05 TEXT-LINE PIC X(60).

*

** Get text into TEXT-TABLE

GET-TEXT-TABLE.

MOVE "TEXT000060" TO LINK-EXTRA. *> 000060 - Characters per line

MOVE "LDG" TO LINK-EXTRA-2. *> LDG - G/L code notes

MOVE "001000" TO LINK-BROWSE. *> Ledger code

MOVE "IMPNOT" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM-NO-CANCEL.

Company or System wide notes

By default the generic Notepad functions allow you to edit and manipulate notes for the current company. From SYSPRO 6.0 issue 005 you can also edit and manipulate system wide notes - that is the notes are common to all companies.

Viewing notes

From SYSPRO 6.0 Issue 010 SP1 there are a number of functions to allow you to include a rich text notepad viewer directly within your program.

The sample program SDK005 demonstrates this feature.

This takes advantage of a function called 'CRTF' in the generic notepad program (IMPNOT) that allows you to pass a note type and note key and have the file name of the RTF file returned.

In addition, on a client/server system, this function will also transfer the RTF file to the client (generating a temporary file name) and return this temporary client file name.

It is then a relatively simple case to move this file name to the user control and have the rich text object refreshed using the 'READ-FROM-FILE' function.

When the READ-FROM-FILE function is executed on a client/server system the temporary file will be removed (so that the programmer does not have to tidy up the system).

A code fragment from SDK005.CBL demonstrating this technique is shown below:

*****************************************************************

** Routine to call Notepad (IMPNOT) to have RTF file moved **

** to client (in c/s system) and return path to RTF file **

** Input : d-customer Customer code **

** Output : d-rtf-file-name Name of rtf file **

*****************************************************************

read-notepad.

move spaces to link-extra.

move "CRTF" to link-extra-1.

move "CUS" to link-extra-2.

move d-customer to link-browse.

move "IMPNOT" to ww-prog-name.

perform call-program-no-cancel.

move link-extra to d-rtf-file-name.

move link-client-server to d-rtf-client-server.

move spaces to link-extra.

The dialog to cause the rich text viewer to read the contents from the file name referenced by D-RTF-FILE-NAME is shown below. Note that the field D-RTF-CLIENT-SERVER is required to ensure that the viewer removes the temporary file in a client/server environment.

* Customer has changed so refresh fields

REFRESH-CUS-FIELDS

MOVE "READ-FROM-FILE" CALL-FUNCTION(1)

EXECUTE-PROCEDURE CALL-RTF

Note that this is a notepad viewer and does not replace the requirement to call the notepad functions for editing notes.

Important - When using the "CRTF" function you must pass a value in link-browse. Failure to pass a non-blank value in link-browse can mean that the default font used when editing a note is the SYSTEM font.

Editing notes

Note that from Issue 010 SP1 Port 15 SDK005 has been updated to handle editing notes directly in the Docking pane. This requires a small change to the information above.

You should use the 'SAVE-TO-FILE' to force the RTF text to be saved back to the file (on the client in a client/server environment). You should then return back to the Net Express program to save the file.

This takes advantage of a function called 'SRTF' in the generic notepad program (IMPNOT) that allows you to pass a note type and note key and have the file name of the RTF file saved.

In addition, on a client/server system, this function will also transfer the RTF file from the client (using the passed temporary file name).

A code fragment from SDK005.CBL demonstrating this technique is shown below:

*****************************************************************

** Notes have changed so save them now **

** Input : d-rtf-file-name File containing rtf notes **

** (on client in c/s system) **

*****************************************************************

002 save-notes.

002 move spaces to link-extra.

002 move "SRTF" to link-extra-1.

002 move d-rtf-file-name to link-extra-1(5:)

002 move "CUS" to link-extra-2.

002 move d-customer to link-browse.

002

002 move "IMPNOT" to ww-prog-name.

002 perform call-program-no-cancel.

002 move spaces to link-extra.

002 move spaces to link-browse.

Important - When using the "CRTF" function you must pass a value in link-browse. Failure to pass a non-blank value in link-browse can mean that the default font used when editing a note is the SYSTEM font.

Testing if notes have changed

You may wish to test if the RTF notes have been changed and prompt the operator to save them. This can be achieved passing the 'CHK-CHG' function to the RTF object.

SDK005 automatically saves any changed notes when navigating to then next/previous customer. See the following dialog code fragment taken from SDK005.GS:

*

* Read next Customer

NEXT-CUSTOMER

MOVE "CHK-CHG" CALL-FUNCTION(1)

EXECUTE-PROCEDURE CALL-RTF

XIF= RTF-CHANGED 1 NOTES-CHANGED

Where the NOTES-CHANGE procedure is defined as shown below:

*

* The notes have changed for the previous item

* so save them now...

NOTES-CHANGED

MOVE "SAVE-TO-FILE" CALL-FUNCTION(1)

EXECUTE-PROCEDURE CALL-RTF

MOVE "note-chg" S-FR-MSG

RETC

See also

S-NEDIT, S-NCOPY, S-NDEL, S-NGRTF, S-NMOVE, S-NTEST, S-NVIEW


Screen Customization Kit

SYSPRO SDK

Screen Customization Kit

SYSPRO Screen Customization Kit

Introduction

This document introduces the Screen Customization Kit and explains how to set it up.

See Screen customization – A worked example for a step-by-step guide to customizing a screenset, Deploying custom screensets for notes about deployment and Additional notes for other information useful when customizing screensets. Also see Developing for 800 x 600 Resolution for guidelines in screen positioning and size.

Important - since the advent of SYSPRO 6.0 Issue 010 more and more customization has been built-in to the SYSPRO User interface as standard. This includes simple-to-use drag and drop changes, VBScript capabilities and management by operator, group and most importantly by Role. This capability has largely superceded the requirement to use the Screen Customization Kit capabilities from prior versions. If you are unsure whether you require the Screen Customziation Kit please contact your local SYSPRO representative.

What is the Screen Customization Kit?

The Screen Customization Kit consist of various items that are needed by a developer to enhance the standard SYSPRO screens. These include:

  • The documentation about how to setup the Screen Customization Kit, how to make changes to the screensets and how to deploy them on a live system (this SYSPRO SDK document).

  • The standard SYSPRO screensets in an editable format

  • A license number that allows the customized screens to be used once deployed.

What is a screenset?

SYSPRO is developed as a multi-tier system. One of the tiers is the user-interface. The user-interface consist of the entire user-experience and includes the various Windows and dialog boxes that are used to interact with the user. A Screenset contains the definition of the user-interface for a program. This includes the windows, dialog boxes and all the controls that reside within them (push buttons, radio buttons, check boxes, entry fields, list boxes etc). In addition a screenset responds to events, performs necessary validation and communicates with the main business logic tier.

The Screenset is edited using the Dialog system. This is a WYSIWIG dialog editor that allows design and manipulation of the screenset. There is a run-time component of the Dialog system that is shipped with SYSPRO that actually runs the screensets.

The Dialog System Editor component forms part of the Net Express development system from Micro Focus.

What can I change using the Screen Customization Kit?

The user-interface tier is used to interact with the user. The Screen Customization Kit allows you to edit this tier. In addition various standard functions have been designed into SYSPRO so that developers using the Screen Customization Kit can perform common tasks.

Examples of what can be done with the Screen Customization Kit include:

  • Uncluttering the screen by removing unused objects or text

  • Re-labeling information to more closely conform to a companies naming conventions

  • Colourising fields or information to highlight an exception

  • Placing additional validation against a field. An example would be to ensure a branch code begins with the letters A or B or C.

  • Splitting an entry field into multiple parts to enforce a structure. An example could be to as a G/L code in 4 parts rather than a single 15 character G/L code.

  • Calling third party software either automatically or conditionally. This third party software can be developed using Net Express or using any language.

  • Calling any standard SYSPRO program with parameters if necessary. An example would be to call the A/R Customer Query passing the Customer number to be shown.

  • Adding passwords to sensitive functions.

  • Adding multimedia facilities to an object. For example allowing a map to be stored against a customer or a photograph to be shown when viewing operators.

  • Adding generic notes to an object.

  • Adding Custom Forms to an object

These are just some examples of what can be done. Like all development systems the opportunities are virtually endless.

How do I obtain the screensets in an editable format?

During the SYSPRO installation process you will be offered the choice of installing the Screen Customization Kit. The default location for the screensets will be C:\Program Files\Syspro\Sck

How do I purchase the Dialog System and Net Express?

The Dialog system is a component of the Micro Focus Net Express development system. This can be purchased from Micro Focus or one of their territory agents. If you are having difficulty obtaining Net Express please contact a Syspro territory agent who can organize it for you.

How do I obtain a license number to run the customized screens?

Contact your SYSPRO software representative. They can organize a license number that will allow your customized screensets to be run.

So how do I get started?

The easiest way is to ensure you have a running version of SYSPRO and then read Screen Customization – A Worked example.

Once I have edited my screenset how should I deploy them?

Once you have edited screenset you may want to deploy them across multiple systems. See the topic Deploying Custom screensets. This includes client/server issues and Unix specific issues.

See also

Screen Customization – A Worked example, Deploying Custom Screensets, Developing for 800 x 600 Resolution


Screen Customization Worked Example

SYSPRO SDK

Screen Customization Kit

Screen Customization – A Worked Example

Introduction

This worked example will show how to add the date that the customer was created to the first window (General Tab) shown in the A/R Query program. This example was developed for SYSPRO 6.0 Issue 007. Subsequent released of SYSPRO have updated the user interface of this and many other programs. However the concepts are similar.

Remember that more recent version of SYSPRO (SYSPRO 6.0 Issue 010 onwards) greatly reduce the requirement for the Screen Customization Kit and therefore you may be able to fully utilize the built-in customization capabilities of the standard software.

You will find that this field is currently shown on the Extra Tab.

It is assumed that you have installed SYSPRO and that it is running. It is also assumed that you are running in a mapped drive environment. There are a few additional notes explained later if you are using a client/server based system.

Directories

An SYSPRO system has various directories / folders that are used by the system. This example assumes the following directories.

Standard program directory \Syspro\Programs

Standard screenset directory \Syspro\Screens

Working directory \Syspro\Work

Base directory \Syspro\Base

In addition we will be using two customized directories to store our customized screens. These will be named:

Custom program directory \Syspro\CusProg

Custom screenset directory \Syspro\CusScrn

Lastly it is assumed that you have downloaded the screensets in an editable format to:

Editable Screensets \Syspro\Sck

Setting up the Dialog System

The Dialog System requires knowledge of the bitmap images used by SYSPRO screensets. This is achieved by copying the files DS.ICN and IMP50.DLL to the Dialog System Bin folder. Perform the following steps:

  1. Exit from the Dialog System

  2. Change to \Syspro\Base

  3. Copy DS.ICN to C:\Program Files\Micro Focus\Net Express 4.0\DialogSystem\BIN

  4. Copy IMP50.DLL to C:\Program Files\Micro Focus\Net Express 4.0\DialogSystem\BIN

Note that the location of your Dialog System Bin folder may be different from that shown above.

Copying the program and screensets

To start customization you should copy the standard A/R Query program from the standard program directory to the custom program directory and rename the program to CUSPEN.

For example you can use the Explorer or simply type:

COPY \Syspro\Programs\ARSPEN.int \Syspro\CusProg\CUSPEN.int

Then you should locate the A/R Query screenset in an editable format and copy it to the customized screenset directory and rename it to CUSPEN.GS

For example:

COPY \Syspro\Sck\ARSPEN.GS \Syspro\CusScrn\CUSPEN.GS

Creating CUSTOM.IMP

Next we will inform the SYSPRO system that whenever we would normally run the standard A/R Query program (ARSPEN) that we will run our customized version instead (CUSPEN). To do this we will create a file called CUSTOM.IMP in the work directory.

You can create a CUSTOM.IMP that looks exactly as shown below:

; CUSTOM.IMP - Customized SYSPRO 6.0 Programs

;

; Col Usage Notes

; ----- ----------------------- ---------------------------

; 1 Type of entry A - Everyone

; C - For a specific company

; G - For a specific group

; O - For a specific operator

; 3-8 Code Company id, group or operator code

;10-15 Custom program All programs in this column will be

; run from the custom directories.

; Defined with CUSPRG= and CUSGUI=

; in IMPACT.INI

;17-22 Original program name This is a standard SYSPRO program name

; that is to be redirected to the custom

; program name

;

; To assist with readability you can place comments at the end of a line

; by preceding them with a semi-colon ';'.

;

;

; Original

; Code Prog Program ;Comment - must be prefixed by ;

; ------ ------ ------ -----------------------------------------------

A CUSPEN ARSPEN ;Run CUSPEN instead of ARSPEN for all users

; End of CUSTOM.IMP

Note that the column spacing of the line beginning ‘A CUSPEN ARSPEN’ must be entered exactly as shown. i.e. 8 spaces between A and CUSPEN.

The CUSTOM.IMP file is processed when an operator logs into SYSPRO. It stores a list of all the customized programs applicable to the operator and whether they are standard programs that should be redirected to a new name.

Setting up the Customized directories within SYSPRO

Login to SYSPRO and select Setup, System Setup from the Main menu. Click on the Other Paths Tab. Change the following entries:

Custom directories – Program directory: \Syspro\CusProg

Custom directories – Screenset directory: \Syspro\CusScrn

Save this screen.

Licensing you company for the Screen Customization Kit

Load the company setup program, change your company and select the Registration Tab.

Ensure that the module Screen Customization Kit is set to Yes and if required enter your new license number at the Registration number: entry field. Save end exit SYSPRO completely.

Testing that all is setup OK

Log into SYSPRO and run the A/R Query as normal. Exit SYSPRO. We are now ready to customize the A/R Query Screenset.

How do I edit the screenset?

Load Net Express using a Windows Icon or from the Windows Start Menu. Select Tools, Dialog System. You should see the Dialog System load.

From the Dialog System select File, Open… Find your screenset to be customized in \Syspro\CusScrn\CUSPEN.GS and open it. You should see the Customer Query Screen ready to be edited.

Click on the Tab page just below the prompt Average number of days to pay (bottom right). There will be dark gray ‘handles’ (square boxes) shown to indicate that the tab page has been selected. This should look similar to that shown below:

If the dark gray ‘handles’ are not shown or are shown around an object then click on the tab page, not on another object. It is very important to ensure that the tab page is selected before continuing.

To add the entry field containing the customer creation date select Object, Entry Field from the Dialog menu bar and drag the entry field to the bottom of the tab page – below the Average number of days to pay prompt.

Once you place the object on the window you need to edit the object properties. To do this you can double click on the entry field object. Depending on how you have configured your system the property dialog box may automatically appear.

Editing the Entry field properties

Change the master field to C1CDTE as this is the data block field that stored the Customer creation date. Change the picture string to 99/99/99. Click OK to save these settings.

Select File, Save to save the changed screenset.

Testing the change

You should now be able to Login to SYSPRO as normal and when you run the A/R Query you should now be able to see the new entry field.

At this point you could return to the Dialog System and add a text field against the new entry field indicating Customer created: remember to save the screenset change, return to SYSPRO and exit back to the menu then reload the program.

What if the new change does not show?

Check each of the following points in sequence.

  1. The first thing to check is that you are editing the correct screenset in the correct directory.

    Exit the Dialog system and reload it.
    Choose File, Open and enter: \Syspro\CusScrn\CUSPEN.GS

    If this again shows the new changes then you have edited the correct screenset.

  2. The second thing to check is that your company license reflects that you have the Screen Customization kit.

    Load the Setup, Company Setup from the main SYSPRO menu and change your company and click on the Registration Tab.

  3. The next thing to check is your System Setup.

    Choose Setup, System Setup from the main SYSPRO menu and click on the Other Paths Tab.
    Check that the Custom directories section near the bottom shows the Screenset directory as \Syspro\CusScrn

  4. Save and Exit SYSPRO (you must do this for the options to take effect).

  5. Check that your CUSTOM.IMP is defined correctly as \Syspro\Work\CUSTOM.IMP

    It’s a good idea to copy the sample CUSTOM.IMP from this document, paste it into Windows NOTEPAD and save it as the required file name.

  6. Reload SYSPRO and reload the A/R Query.

    If you are still having a problem then contact your local SYSPRO support agent.

Screensets and their Associated Programs

When a SYSPRO program is created the business logic is developed using Net Express and compiled into an intermediate code program (usually having an extension of .int but it can be .gnt). This program has a data block compiled into it that is used to communicate with it’s screenset. This program and the data block defined in the screenset must not be changed.

Therefore whenever screen customization is performed it’s important to use and deploy the screenset and program together.

If you ship just the screenset then you may well get a data block inconsistency problem. This is because some time later the standard program may have it’s data block modified and then it will not match the customized screenset.

As shown in the worked example the standard program should be copied to the customized program directory (with it’s new name) and the screenset from the Screen Customization Kit directory must be copied to the customized screenset directory (with it’s new name).

Screensets and user-control programs

In SYSPRO various programs have more sophisticated controls than the standard ones edited using the Dialog System. These include listviews, toolbars, status bars, tree views etc. Each of these objects is added to the screenset as a programmed control and each have a user-control program. These user-control programs are deployed in the base\bin directory.

For example you will see that the A/R Query program has several programs in the bin directory beneath the base directory. You will see programs called

base\bin\ARSPEN??.?NT.

These include ARSPENLV.INT which is a listview user-control program (and APSPENL?.INT which are different list view user-controls).

When using the screen customization kit you will not have to amend these user-controls in the same way that you do not have to amend the program ARSPEN.INT itself.

Copy the user-controls

However the user-controls are tied to the data block, just as the programs and screensets are. Therefore if the program has any user-controls that these should be copied in a similar fashion to the programs.

For example COPY ARSPEN??.?NT to CUSPEN??.?NT.

Once this has been done you must then run the program called SDKBIN (load SYSPRO and select File, Run, SDKBIN). This program can only be run by a system administrator and on a mapped drive system.

Enter the following:

Original program name: ARSPEN

New program name: CUSPEN

Click on Start... and confirm your choice.

(This program will edit the user-controls BIN\CUSPEN??.?NT and every occurrence of the name ARSPEN will be changed to CUSPEN)

Update the screenset

As these programs are called directly from the screenset you will now have to edit the screenset to ensure that the new user-control names are used. To do this is fairly simple:

  1. Edit the screenset

  2. Double click on each listview to edit it’s properties and change the program name

  3. Edit the global dialog and search for the original program name (such as ARSPENLV) and change the dialog to use the new name (eg CUSPENLV)

  4. Save the screenset

Remember to include the customized user-controls when deploying the screenset.

See also

Screen customization overview, Deploying a customized screenset, Additional information


Screen deployment

SYSPRO SDK

Screen Customization Kit

Deploying Custom Screensets

Introduction

This section gives recommendations about how you should deploy customized screensets at one or more SYSPRO sites.

The recommendations assume you are trying to deploy a customized screenset (and program and user-controls) called CUSPEN as used in the Screen customization – A worked example.

Setting up the directories/folders

  1. Create a customized program and customized screenset directory.

    It is assumed you created \Syspro\CusProg and \Syspro\CusScrn

  2. Copy your saved program to \Syspro\CusProg\CUSPEN.int

  3. Copy your customized screenset to \Syspro\CusScrn\CUSPEN.GS

  4. Copy your saved user-controls to \Syspro\Base\Bin\CUSPEN??.int

  5. Create a CUSTOM.IMP file in \Syspro\Work\CUSTOM.IMP. You can use the sample included in this document.

Setting up SYSPRO

  1. Login to SYSPRO and use the System Setup to define your Customized program and screenset directories.

  2. Load the Company maintenance and ensure you are licensed to use the Screen Customization Kit.

  3. Save and Exit SYSPRO.

    When you next login to SYSPRO you will be able to run CUSPEN.

Customization per Company, Group or Operator

Up till now we have defined in CUSTOM.IMP that the customization is available for all users. This is indicated by the A at the beginning of the line in CUSTOM.IMP.

You can specify a C to indicate a specific company, G to indicate a specific group or O to indicate a specific operator. After the indicator character leave a single space and then enter the company, group or operator code.

When an operator logs into SYSPRO the lines that match in CUSTOM.IMP are read into memory and these will then indicate the custom programs available.

See the following example CUSTOM.IMP

; Original

; Code Prog Program ;Comment - must be prefixed by ;

; ------ ------ ------ -----------------------------------------------

A CUSPEN ARSPEN ;Run CUSPEN instead of ARSPEN for all users

O RUSS CUSP10 GENP10 ;Run CUSP10 instead of GENP20 for operator RUSS

G ADMIN CUSP05 ;ADMIN group can access custom program CUSP05

C Z CUSMNT ;Company Z operators can use program CUSMNT

; End of CUSTOM.IMP

Additional notes on Standard and Custom *.IMP files

Customized Import Files (*.IMP)

SYSPRO uses various ASCII text import files (*.IMP) to provide information about the standard system.

For example the file IMPPRG.IMP contains a list of all the standard SYSPRO programs. When you use the File, Run facility and browse on programs the IMPPRG.IMP file is used to provide the list of programs. This file is used elsewhere in SYSPRO – for example when you add a program to the Favorites menu the wizard uses IMPPRG.IMP to provide the default program description.

Whenever a SYSPRO program reads one of the standard text import files, once it has finished reading the standard import file, it will then look for a custom equivalent and append this information to it’s list.

When deploying custom programs it is recommended that you ship an equivalent set of custom text files in the custom program directory. Note that on a client/server system these reside on the server.

Text import files include:

Standard | Custom | Notes
IMPPRG.IMP | CUSPRG.IMP | List of programs
IMPFIL.IMP | CUSFIL.IMP | List of files
IMPMEN.IMP | CUSMEN.IMP | List of items in menu
IMPMOD.IMP | CUSMOD.IMP | List of modules
IMPHLP.IMP | CUSHLP.IMP | Pointer to on-line help information
IMPPRT.IMP | CUSPRT.IMP | Library of SYSPRO style printer attributes
IMPPSS.IMP | CUSPSS.IMP | Program function passwords
IMPSEC.IMP | CUSSEC.IMP | Security Activities and Fields

Notes on deploying Client/Server systems

There are several implications to deploying SYSPRO customized screensets in a client/server environment. These mainly revolve around the fact that some components run on the server and some on the client. In addition SYSPRO provides a mechanism for automatically uploading components from the server to the client when required.

Simple case with no auto-upload

When running in a client/server environment the programs run on the Server and that the screensets and user-controls run on the Client. Use the following example to see where each element should be installed.

Setting up the directories/folders

  1. Create a customized program directory on the server called \Syspro\CusProg

  2. Create a customized screenset directory on the client called \Syspro\CusScrn

  3. Copy your saved program to the server \Syspro\CusProg\CUSPEN.int

  4. Copy your customized screenset to the client \Syspro\CusScrn\CUSPEN.GS

  5. Copy your saved user-controls (if any) to the client \Syspro\Base\Bin\CUSPEN??.int

  6. Create a CUSTOM.IMP file on the server called \Syspro\Work\CUSTOM.IMP

  7. You will need to manually edit your IMPACT.INI on the client and ensure there is a line that reads
    CUSGUI=\Syspro\CusScrn

Setting up SYSPRO to auto-upload the screensets and user-controls

It can be logistically difficult to ensure that the client components (screensets and user-controls) are installed on all Clients simultaneously, especially in a WAN environment.

SYSPRO allows you to deploy your screensets and user-controls onto the Server so that they will be uploaded to each client on-demand.

To enable the auto-upload you should initially ensure that SYSPRO client and server have been setup as discussed in the previous example.

In addition you should:

  1. Create a customized screenset directory on the server called \Syspro\CusScrn

  2. Create a customized user-control directory on the server called \Syspro\Base\Bin

  3. Copy your customized screensets and user-controls into these directories.

  4. Ensure that the SYSPRO System Setup has the customized screenset directory defined as \Syspro\CusScrn

    The logic used to determine whether the screenset should be uploaded is that the size of the screenset on the server and the size (if any) of the screenset on the Client are compared and if they differ then Server screenset and its associated user-controls will be uploaded to the client. This comparison occurs 'just before' the screenset is loaded.

    Therefore it is recommended that whenever any changes are made that you ensure that the screenset changes in size. This can be done by having a dummy message box that you add for each change that you make.

Deployment considerations on a Unix Client/Server environment

The following additional considerations apply when the server component is a Unix Server.

When transferring a screenset and any user-controls (for automatic upload) to the Unix system you must ftp the screenset and user-controls in binary.

The file names are case sensitive under Unix. So for example the screenset could be called CUSPEN.GS and the user-controls called CUSPENLV.INT (note all uppercase). The base\bin directory on Unix will be called bin (note lowercase) beneath the Working directory.

See also

Screen customization overview, Screen customization – A worked example, Additional information


Screen Customization Additional Notes

SYSPRO SDK

Screen Customization Kit

Additional Notes for Screen Customization

Introduction

This section gives additional notes about screen customization.

Standard Functions available from the Screenset

SYSPRO provides many functions that can be called from the screenset. These are standard messages that all programs are designed to accept and process. An example is the ability to call another standard SYSPRO program. Thus for example, you could add a push button to a screen for it to call a Query.

The logic to use these standard functions all follow a similar style.

  1. Move any required parameters to a standard data block field

  2. Move the function into the standard field called S-FR-MSG

  3. Return to the calling program using a RETC

  4. Optionally process any returned parameters or status codes

For example to call a program called INVPEN (the Inventory Query) you can use the following dialog:

MOVE "INVPEN" S-FR-PAR

MOVE "S-CALL" S-FR-MSG

RETC

There are many of these functions which can be extremely useful when using the Screen Customization Kit. See Dialog functions by name and Dialog functions by type.

Editing the data block whilst customizing a screenset

As the original program (and any user-controls) have been compiled with the original data block you can only make the following changes to the data block otherwise an inconsistency will occur.

  • You must NOT change the total length of the data block

  • The last field must be defined as S-END X 3

  • The standard data block fields (the ones starting with S- at the beginning must not be changed or any fields inserted between them). The only exception to this are the two fields that can be edited as required. They are:

S-CALLOUT-MSG X 10
S-CALLOUT-PAR X 300

  • If you do edit one of these two fields you must make sure that your fields still add up to the 310 bytes that they originally used. For example I have replaced S-CALLOUT-MSG with four fields that add up to the original 300 bytes.

S-CALLOUT-MSG X 10
MY-FIELD-1 X 30
MY-FIELD-2 S 12.2
MY-FIELD-3 9 6.0
MY-FIELD-REST X 250

Screen Resolution

SYSPRO 6.0 is designed to be used on a Windows terminal with at least 800 x 600 resolution (knows as Super VGA or SVGA).

SYSPRO 6.0 will work on terminals with higher resolutions. In many cases windows in SYSPRO programs can be stretched to take advantage of the extra real estate that this provides. For example to be able to view more items on the main menu or browses to show more columns of information.

However it is important when developing SYSPRO 6.0 applications to ensure that your user-interface works successfully in the basic 800x600 environment.

For more information see the topic Developing for 800 x 600 Resolution for guidelines in screen positioning and size.

See also

Screen customization overview, Screen customization – A Worked example, Deploying a custom screenset, Dialog functions by name, Dialog functions by type, Developing for 800 x 600 Resolution


SYSPRO SDK

Articles

Animating a Screenset from within SYSPRO 6.0

Animating a Screenset

Many SYSPRO developers have wanted to be able to animate their screensets whilst they are actually running from within SYSPRO. Especially where the program appears to receive an unexpected message or the screenset appears to receive an unexpected value in the data block.

In the following explanation it is assumed that you are trying to animate the program and screenset called SDK001 which is part of the Software Development Kit.

SYSPRO 6.0 issue 006

The standard routine to call a screenset in PROBEGIN.PRO called CALL-DS has been enhanced in SYSPRO 6.0 issue 006 to make the task of animating a screenset as easy as possible.

Simply compile your source code program for animation as normal (for example COMPILE /A SDK001) and animate it using Net Express as normal.

When you break into your program move a Y to the new field SCREENSET-ANIMATOR. If you do not have this field then you do not have the latest SDK.

This forces the CALL-DS routine to invoke the screenset animator the next time it is called.

Disabling the Screenset Animation

You can disable the screenset animator by moving N to SCREENSET-ANIMATOR before the CALL-DS. This allows you to toggle screenset animation on an off as many times as you require in your program.

If required you can even add the line

MOVE "N" TO SCREENSET-ANIMATOR.

in your code to cause screenset animator to be invoked next time CALL-DS is used in the program.

You do not even have to compile your program for animation nor run your program using Net Express - simply click on your desktop Icon to run SYSPRO 6.0 as normal and when you run your program the screenset animator will be invoked.

Everything will be Animated

Remember that once the screenset animator has been invoked ANY screenset run from then onwards will be animated. For example calling a browse will animate the browse screenset as well. To avoid the menu being animated the QUIT-DS routine in the original program disables the screenset animation function.

Notes

You must have installed and setup Net Express on you PC for the above to work successfully.

You must ensure that you are using the SDK001.GS screenset and not SDK001.RS.

When animating a screenset the screenset animator may generate unexpected events, such as LOST-FOCUS and OTHER-SCREENSET, which may differ slightly from the events generated when the screenset is run without animator. If these events are preventing you from animating the screenset successfully then you could temporarily disable these events (remember to restore them again after you have finished animating your screenset).

See also

Deploying custom screensets, CALL-DS, QUIT-DS


Creating Help

Introduction

This article explains how you can create and deploy help content for your custom Net Express applications. It is assumed that you wish to create help content that will be shown in the SYSPRO Help system and that you want your help topics to have a similar look-and-feel to standard SYSPRO Help.

The SYSPRO Help system also allows you to provide your help content in other formats, such as CHM. This will also be covered.

Note: This article is aimed at SYSPRO 6.0 issue 009 and later. Prior versions use a different architecture and are not covered by this article. For other new issue 009 features see the topic What's New about SYSPRO 6.0 Issue 009.

Also note that many of the Setup programs have context sensitive help available by clicking the question mark ('?') on the title bar. Context help is explained in the Creating Context Sensitive Help topic.

SYSPRO Help Architecture

The SYSPRO Help content is primarily provided by a set of HTML files that reside in the base\htmlhelp folder. In addition there are subfolders that provide the infrastructure for the help system.

When you press F1 from within a Net Express program the SYSPRO Help system looks for the help file called htmlhelp\??????.htm where ?????? is the name of the program. The help content is shown in the SYSPRO Help browser.

For example if you load the Stock Code browse program (IMPBST) and then press F1 the SYSPRO Help system loads the help file htmlhelp\impbst.htm into the SYSPRO Help browser.

All the SYSPRO Help files and folders should be in lowercase.

Installing updates to SYSPRO software

The regular software updates provided on the SYSPRO Support Zone contain associated help files in HTML format. These are handled in much the same way that the programs and screensets are handled. The files are unzipped and moved to the appropriate folders (on the server in a Client/Server installation). This ensures that you will always have the latest up-to-date help content.

Client/Server considerations

On a Client/Server system the SYSPRO Help browser uses help files from the Client base\htmlhelp folders. However a similar set of help files reside on the Server. When the SYSPRO Help system is invoked (e.g. by pressing F1) the Help system will ensure that the Client help files are up-to-date and, if required, will transfer the latest help content from the Server to the Client. This process is known as self-healing.

IMPHLP.IMP

By default pressing F1 will locate and show a file called base\htmlhelp\??????.htm in a browser, where ?????? is the program name. The SYSPRO file redirector file IMPHLP.IMP allows this to be changed. For example the help file for IMP030 can be configured to be base\htmlhelp\impbst.htm. In addition you can provide a custom version of this help file called CUSHLP.IMP in the custom program folder.

Developing help for your custom programs

The following section explains the steps you can take to develop your own help content that will have a similar look-and-feel to the standard SYSPRO Help content.

The remainder of this example assumes your are trying to describe a custom program called CUST10.

To make this process as easy as possible a template help file has been provided. The template is found at base\htmhelp\sdk001.htm and can be viewed by pressing F1 after you have run SDK001 from the SYSPRO menu. SDK001 is provided as part of the SDK and the source code to the program is described in this SDK documentation.

Copy the template

First you should copy sdk001.htm to cust10.htm. The file cust10.htm should be saved into the base\htmlhelp folder - remember to keep it lowercase.

Edit your help file

Next you should edit cust10.htm. You can use a simple text editor, such as Notepad, or alternatively you can use a WYSIWYG HTML editor or a more sophisticated XML editor such as XML Mind. Where possible you should ensure that the standard structure of the existing XML is not changed.

The help template consists of XML elements and values. The e.net part of this documentation provides a brief XML Overview and introduces the concept of Well Formed XML.

Warning: inappropriate XML/HTML elements may cause your help content to fail to be shown as expected (or at all). It is recommended that you follow the guidelines provided in this article although a large number of XML and HTML elements can be used.

Using your editor you should then change the cust10.htm file to provide your content. The template is described below under the heading 'Structure of a SYSPRO Help file' below.

You should start by performing a global find and replace of 'sdk001' to 'cust10'. The template contains some simple text that can be removed/changed as necessary. In addition 10 Tabs and 10 Tasks are included. You should change the description and content of these and remove the Tabs and Tasks that you do not require. The reason that 10 Tabs and 10 Tasks were included in the template is that its is easier to remove the ones you do not need than create new ones.

Once you have finished editing cust10.htm you should save it in base\htmlhelp.

You can test the look-and-feel of cust10.htm by loading your CUST10 program from the main SYSPRO menu and pressing F1.

General notes on editing the XML content

There are a number of common tags that can be used as follows.

Paragraphs should be surrounded with <p> and </p> tags.

Bold text should be surrounded with <strong> and </strong> tags.

Italic text should be surrounded with <em> and </em> tags.

Character entities should be used when your content is to show the < > and & characters.

< - &lt;

> - &gt;

& - &amp;

Links to other programs should be surrounded with <a> and </a> tags.

See the following example:

<a href="invpen.htm" title="Inventory Query"><i>Inventory Query</i></a>

In this case the 'href' attribute points to a physical file in base\htmlhelp, the 'title' attribute is the ToolTip that will be used and the text against between the <i> and </i> tags is the shortcut text that will be shown using a SYSPRO Help style.

You can incorporate several pre-defined images to help draw attention to a paragraph. These include Notes, Important, Caution, Tip and Warning elements. The following example is used to provide a Note:

<img alt="[Note]" src="images/note.png" /><p>Note that...</p>

In this case the 'alt' attribute defines the ToolTop and the 'src' attribute define the path to the image.

The current list of standard images are shown below:

<img alt="[Note]" src="images/note.png" />

<img alt="[Important]" src="important.png" />

<img alt="[Caution]" src="images/caution.png" />

<img alt="[Tip]" src="images/tip.png" />

<img alt="[Warning]" src="images/warning.png" />

Structure of a SYSPRO Help file

This section provides a detailed walk through of the template sdk001.htm and provides a guide as to what you should edit.

Remember to copy the template 'sdk001.htm' to 'cust10.htm' and perform a global replace of 'sdk001' with 'cust10'.

XML prolog and <head> tags

The initial part of the template consists of part of the infrastructure that is required in every SYSPRO Help file to provide the standard look-and-feel.

This consists of the <?xml> prolog, <!DOCTYPE> and <head> tags. It is recommended that this part of the template is not changed in any way.

The <body> tag

The <body> tag describes the main 'body' of text shown in the browser. This is where we are going to show our content. All the editing we are going to do will be within the <body> tag.

Navigation path

The first tag within the <body> defines the navigation to the program. This is defined as follows:

<div xmlns="" class="chapter" lang="en" xml:lang="en">

Module &gt; Program description

The navigation path appears above the program description.

The template includes the sample text Module &gt; Program description that you should replace as required.

Note the use of the character entity &gt; to represent a > character.

Program Description

If you search for the string 'Program Description' you will find it inside an <h2> tag. You should replace this text with your custom program description. This is shown as a heading to your program overview. See the following example:

<h2 class="title">

<a id="sdk001"></a>

Program Description

</h2>

Program Overview

The Program overview consists of one or more paragraphs describing the use of your program. The template contains the following program overview fragment:

<div xmlns="http://www.w3.org/1999/xhtml" class="sect1">

<p>This help text is not the help for SDK001 but is to be used as a template for developers to create help text for their own programs.

</p>

<p>This is the program overview where you should describe your program.

</p>

Remember that the paragraphs can contain bold and italic text to emphasize the content and links to other programs or features. Also various images, such as Notes, can be used to draw attention to a particular paragraph. The template 'sdk001.htm' demonstrates some of these features.

Tab bar

The template contains 10 sample Tabs on a Tab bar. The Tab bar is designed to provide one-click navigation to parts of your help content. It is shown immediately below your program overview. These parts can represent the prompts on a physical Tab page or Dialog box or may represent any logically separate section of your application.

You should change the text 'Tab 1', 'Tab 2' etc to represent your own descriptions. The first Tab description is defined with the following XML:

<li>

<a href="javascript:showInfo(1,10,'content')">Tab 1</a>

</li>

Remember to remove the Tab bar definitions that you do not require.

Task menu

Simlarly to the Tab bar described above the template contains 10 sample Tasks on a Task menu. The Task menu is designed to provide one-click navigation to parts of your help content. It is shown to the top right of your program overview. These parts can represent tasks that the operator is most likely to perform.

You should change the text 'Task 1', 'Task 2' etc to represent your own task descriptions. The first Task description is defined with the following XML:

<li>

<a href="javascript:showInfo(1,10,'task')">Task 1</a>

</li>

Remember to remove the Task menu definitions that you do not require.

Related programs

The template contains a list of Related programs - this provides quick access to other programs that may be of interest to the Help reader. These are shown as a list beneath the Task menu. You can change the single item provided in the template or add to the list as required. The XML for the Related program list is shown below:

<li>

<a href="invpen.htm">Inventory Query</a>

</li>

To add to the list simple insert more <li> items containing <a> tags.

Tab content

The template contains 10 sample pieces of tab content. This is the description that appears below the Tab bar when the appropriate Tab name is clicked. The first sample contains more content, the other examples are quite terse.

There are various parts to the Tab page. The Tab Heading is shown above any Tab content. The Tab Description describes the usage of the Tab and is shown below the Tab Heading. The remainder of the Tab content can contain paragraphs, lists, notes etc. Typically most SYSPRO Help Tab pages describe the prompts and other user-interface elements. These are shown in a 'definition lists' that are made up of the Definition Term and the Definition Detail.

The Tab Heading is described as follows:

<div class="titlepage">

<div>

<div>

<h3 class="title">Tab 1</h3>

</div>

</div>

</div>

The template contains a sample Tab Description described as follows:

<p>This text describes the first Tab. Typically you would describe the prompts and elements that are part of the user-interface. These are shown in a definition list as demonstrated below.</p>

The Tab Definition Term showing the prompt name is described as follows:

<dt class="term">Prompt 1</dt>

The Tab Definition Detail describing the prompt usage is described as follows:

<dd>

<p>This is the description of the first prompt.</p>

</dd>

Task content

The template contains 10 sample pieces of Task content. This is the description that appears below the Tab bar when the appropriate Task name is clicked. The first sample contains more content, the other examples are quite terse.

There are various parts to the Task page. The Task Heading is shown above any Task content. The Task Description describes the Task and is shown below the Task Heading. The remainder of the Task content typically consists of an ordered list but can contain paragraphs, lists, notes etc.

The Task Heading is described as follows:

<p class="title">

<b>Task 1</b>

</p>

The template contains a sample Task Description described as follows:

<div class="procedure">

<p>You describe the task here. This could include text explaining when you should run the task. The remainder of the task description is typically shown in a list.

</p>

Typically you would describe the detail steps of the Task using an ordered list. This is done as follows:

<li>

<p>Step 1 is explained here</p>

</li>

Notes about deploying your own help content

Your help content can be deployed in one of two ways:

1. Copy the files into the base\htmlhelp folder (on the server)

2. Create a self-extracting EXE and copy the EXE to base\upgrade (on the server)

The advantage of using the second method in a Client/Server environment is that when your help files are moved to the base\htmlhelp folder on the server the htmlhelp\_version.txt file will have the UPD= entry updated to reflect the current server date and date. This will ensure that the files are self-healed to the client when they next invoke the SYSPRO Help system.

Note the following

When creating your own help content using the template 'sdk001.htm' provided please be aware of the following:

Your help content will not be included in the Search facility available from the SYSPRO Help.

Your help content will not be included in the menu system shown in the left-hand pane.

As your help content will be deployed into the base\htmlhelp folder (on the server in a Client/Server environment) you should avoid using the same file names as existing SYSPRO programs.

Note that file names beginning with an underscore ('_') are used to represent topics and features in the standard SYSPRO Help system. You should not create or change any files beginning with an underscore.

You should not add, delete or change any files that are shipped as part of the standard SYSPRO help system. This includes the files in base\htmlhelp and it's subfolders.

Custom Notes

The SYSPRO Help system has the ability to edit Custom Notes. These Custom Notes will automatically be incorporated within the Help text - immediately below the Program Overview.

Only an Adminitsrator can edit Custom Notes using the built-in editor.

Custom Notes are stored in the htmlhelp\custom_notes folder using the program name and a '.xml' extension. For example Custom Notes for the program IMPBST are stored as htmlhelp\custom_notes\impbst.xml. (note the file name should be lowercase).

You can deploy Custom Notes for standard SYSPRO programs or your own programs by copying your notes to this folder.

Format of Custom Notes

The custom notes placed in this folder must have the following opening tag:

<program><![CDATA[

and be closed as follows:

]]></program>

For example the following sample file called impbst.xml could be created in base\htmlhelp\custom_notes

<program><![CDATA[This is my help text for stock code maintenance]]></program>

On a client/server system this Custom Note should be placed in the server's htmlhelp\custom_notes folder and when each operator presses F1 (or invokes the help by any other means) the Custom Notes will be uploaded to the client before any help is shown.

The file htmlhelp\_version.txt on the server has a CUS= entry that defines the date and time that the custom notes on the server were last changed. If you place your own notes directly into the htmlhelp\custom_notes folder then you should also update the CUS= entry in htmlhelp\_version.txt to the current server operating system date and time to force the custom notes to be uploaded to the client.

Important note about the content of Custom Notes

As the custom notes are shown in a browser it is possible to use HTML tags to format your text and provide hyperlinks to other documents. It is recommended that you only use the most basic HTML tags such as <strong> for bold, <em> for italic and <a> for anchor (links to other documents).

Important: Incorrect use of HTML tags in your custom notes may cause the SYSPRO Help to be adversely affected.

Showing CHM help content

Apart from redirecting the help for one program to show the help for another program you can also direct the help for your custom program to show help in a CHM format file.

CHM files are a common format for help content.

To redirect your custom program (e.g. CUST10) to show a help file called CUSTOM.CHM you can add the following line to a file called CUSHLP.IMP IMPHLP.IMPstored in the custom program directory. This file must have a similar format to the standard file IMPHLP.IMP.

; CUSHLP.IMP - SYSPRO 6.0 Custom Help Redirector

;

[HelpBody]

Program Num URL

------ --- ------------------------------

cust10 all chm:custom.chm ;Call CUSTOM.CHM

Note that there is no self-healing of CHM files. You must ensure that the CHM file resides in the base folder on the client system.

See also

Creating Context Sensitive Help, XML Overview, Well Formed XML, What's New about SYSPRO 6.0 Issue 009, IMPHLP.IMP


Customizable Listviews

Introduction

Listview controls are used throughout SYSPRO to show data in a grid.

You can use CTRL+F1 to see a list of functions that allow changing the appearance of the listview. This includes the font and color.

This article covers more advanced customization that can be applied by the developer from SYSPRO 6.0 issue 007 onwards.

What Customization is Available?

As a developer you can configure a 'style' against each row in a listview. The 'Style' can be used to represent some exception or other indicator that makes the row significant.

For example when presenting a Trial Kit the developer may wish to highlight items that have insufficient stock.

A 'style' is a two character code applied to a listview row. The operator can configure the appearance of a style - for example style '01' may be shown in red to highlight some important information.

Once added, the operator can use CTRL+Q to customize their listview – they can assign attributes for each style.

Note that you should use CTRL+W to toggle the customization on/off.

For example the Job Logging program (6.0.006 onwards) has been update to highlight failed processes and transactions failures. See the following:

How do I add Customization to my listviews?

There are a few simple steps to be used to customize a listview. These are detailed below.

1. Add two new fields to the screenset data block.

LVITEM-STYLE-INDEX 9 2

This item should be added as part of the LVIEW-ITEM group. See the following example:

LVIEW-ITEM 50

LVITEM-TEXT X 50.0

LVITEM-LENGTH C5 4.0

LVITEM-STYLE 9 2.0

LVITEM-OBJECT OBJ-REF

LVITEM-STYLE-INDEX 9 2.0

LVDATA-STYLE-INDEX 9 2

This item should be added as part of the LVIEW-DATA group. See the following example:

LVIEW-DATA 20

LVDATA-ICON 9 2.0

LVDATA-OBJECT OBJ-REF

LVDATA-STYLE-INDEX 9 2.0

LVDATA-COLUMN1 X 30.0

LVDATA-COLUMN2 X 30.0

etc...

2. Define the descriptions of the listview styles

Immediately beneath the existing global dialog that adds the listview header you should define the descriptions of the styles so that the operator can customize them.

This is done by moving a comma separated list of style descriptions to the field S-FR-EXT and calling a new function. See the following example to be added beneath the 'ADD-HEADER' global dialog:

MOVE "Quantity less than zero,Quantity is zero," S-FR-EXT

MOVE "SET-STYLE-TYPES" CALL-FUNCTION(1)

EXECUTE-PROCEDURE CALLOUT-LVIEW

This defines the styles as follows:

Style 1 - Quantity less than zero

Style 2 - Quantity is zero

You may define up to 10 style descriptions, each separated by a comma.

3. Trap the new user-event to allow customization

Against the existing USER-EVENT in the window dialog add the following line:

IF= 60021 $EVENT-DATA ASK-ROW-STYLES

4. Define the ASK-ROW-STYLES procedure for customizing the listview

Add the following dialog against the window:

ASK-ROW-STYLES

MOVE "S-CALL" S-FR-MSG

MOVE "IMPLVS" S-FR-PAR

RETC

MOVE "SAVE-STYLE-TYPES" CALL-FUNCTION(1)

EXECUTE-PROCEDURE CALLOUT-LVIEW

When the operator presses the appropriate function key to customize the listview (See CTRL+F1) this routine will call the program IMPLVS to allow you to configure the styles. Once configured the listview will be called to refresh the contents with the new style.

5. Define the style number against each row

Typically the program logic will be responsible for defining the style number against each row.

When adding items to the data block coding similar to the following needs to be added. In this example a quantity of less than zero will have a style 1 and a quantity equal to zero a style of 2.

MOVE ZERO TO D-LVDATA-STYLE-INDEX(D-LVDATA-MAX).

IF QUANTITY < ZERO

MOVE 1 TO D-LVDATA-STYLE-INDEX(D-LVDATA-MAX)

ELSE

IF QUANTITY = ZERO

MOVE 2 TO D-LVDATA-STYLE-INDEX(D-LVDATA-MAX).

Note - A style of zero indicates that the listview default appearance will be used. ie. no style.

If you use the INSERT-LIST-ITEM function then you should move in the style as shown below.

MOVE 2 TO D-LVITEM-STYLE-INDEX(1)

Where 2 is the style.

Notes

The current style is automatically returned in D-LVIEW-ITEM-STYLE(1) when using the RETRIEVE or RETRIEVE-LIST-ITEM functions.

To update a row with a new style then move the new style number to D-LVIEW-ITEM-STYLE(1) and use the UPDATE-LIST-ITEM function.

Remember to use CTRL+Q to customize the listview (assigning attributes for each style) and then use CTRL+W to toggle the customization on/off.

See also

User Control Overview, User Controls - Adding Listview Control Programs


Deploying Custom Programs

Introduction

This article provides an overview to setting up, testing and deploying custom programs. It also gives some guidelines to deploying client/server systems for both Windows NT and Unix platforms.

Custom Directories

SYSPRO has two sets of directories for programs and screensets.

  • The standard directories that are installed when SYSPRO is installed,

  • Customized directories that developers can used to deploy their programs.

It is highly recommended that these customized directories are used when testing and deploying custom (non-standard) programs.

To setup a set of custom directories do the following:

    1. Create the appropriate directories.
      For example \rnd60\prg and \rnd60\gui

    2. Load the SYSPRO System setup program and use the Other Paths tab

    3. Enter your directory names in the Customized directories fields

    4. Create a file called CUSTOM.IMP in your working directory.
      See below for details of the CUSTOM.IMP file

CUSTOM.IMP

This file is used to define all your customized programs. It should be defined in your working directory (on the server in a client/server system). This file can be edited with any text editor (such as NOTEPAD on Windows or vi on Unix).

The entries in the file are prefixed by a code that identifies whether the programs can be run by everyone (system-wide), or only for certain companies, groups or operators.

In addition it is possible to redirect a standard program to a customized program. For example if you wish to deploy a customized version of the Stock Code browse (IMPBST) you can inform SYSPRO that every time IMPBST runs it should call CUSBST instead.

It is recommended that you add comments (prefixed with ;) to assist in later identification.

See the following example

; CUSTOM.IMP

; Code Prog Program ;Comment (must be prefixed by ;)

; ------ ------ ------ ----------------------------------------------

A CUSBST IMPBST ;Run CUSBST instead of IMPBST for all users

A CUSP10 ;CUSP01 is a custom program for all users

C 1 CUSPEN ;CUSPEN is a custom program in company 1

G ADMIN CUSP01 ;CUSP01 is a custom program for users

; ;belonging to group ADMIN

O USER CUSP20 ;CUSP20 is a custom program for operator 'USER'

Note that CUSTOM.IMP file is only used when the company has the Screen Customization Kit module installed.

Customized Import Files (*.IMP)

SYSPRO uses various ASCII text import files (*.IMP) to provide information about the standard system.

For example the file IMPPRG.IMP contains a list of all the standard SYSPRO programs. When you use the File, Run facility and browse on programs the IMPPRG.IMP file is used to provide the list of programs. This file is used elsewhere in SYSPRO – for example when you add a program to the Favorites menu the wizard uses IMPPRG.IMP to provide the default program description.

Whenever a SYSPRO program reads one of the standard text import files, once it has finished reading the standard import file, it will then look for a custom equivalent and append this information to it’s list.

When deploying custom programs it is recommended that you ship an equivalent set of custom text files in the custom program directory. Note that on a client/server system these reside on the server.

Text import files include:

Standard | Custom | Notes
IMPPRG.IMP | CUSPRG.IMP | List of programs
IMPFIL.IMP | CUSFIL.IMP | List of files
IMPMEN.IMP | CUSMEN.IMP | List of items in menu
IMPMOD.IMP | CUSMOD.IMP | List of modules
IMPHLP.IMP | CUSHLP.IMP | Pointer to on-line help information
IMPPRT.IMP | CUSPRT.IMP | Library of SYSPRO style printer attributes
IMPSEC.IMP | CUSSEC.IMP | Security Activities and Fields

Re-indexing

Note that the re-indexing utility uses the entries in IMPFIL.IMP and CUSFIL.IMP so that if you ship a CUSFIL.IMP you do not have to develop a re-index utility for your file(s). Any extra files defined in CUSFIL.IMP will appear at the bottom of the list of files in the Re-index listview. Place a 'module' section in CUSFIL.IMP (a line beginning ;Mod) so that the re-index will recognize this as a file definition.

User defined menus

Note that the menu program uses IMPMEN.IMP and CUSMEN.IMP to show the tree view menu structure so that you can ship your own menu and it will automatically be appended to the standard menu.

Notes on deploying Client/Server systems

There are several implications to deploying SYSPRO custom programs on client/server systems.

These include:

    • Source code implications

    • Dialog system implications

    • Compiling and Deployment implications

Source code implications

The majority of SYSPRO standard functions are cross-platform. They take into account whether the system is standalone (mapped) system, or a client/server system running in either Windows NT/2000 or a Unix server.

Areas to watch out for include:

  • Avoid hard coding a path as this may not exist or not be valid on a different operating system.

  • File names on Unix are case sensitive whereas on Windows they are not. One technique is to always use UPPERCASE for file names. Remember that program names have a .int and .gnt suffixes on Unix in lowercase.

  • Remember that indexed files on Windows have .DAT and .IDX extensions whereas on Unix they have no extension for the data portion and .idx for the index portion.

  • If you have to differentiate between systems the standard linkage field LINK-OS contains a 'U' if you are running on Unix.

  • If you wish to issue operating system commands remember that they may not be available on one or more platforms or may work differently between versions. Use the functions in PROBEGIN.PRO to issue the commands (see EXECUTE-COMMAND-ON-SERVER and EXECUTE-COMMAND-ON-CLIENT).

  • Do not issue calls to the operating system. For example it is easy to issue Windows API calls from within your program, however when this program is deployed to a Unix environment these will not work. One technique is to use a user control program so that the command is always issued from the Client system. Standard SYSPRO programs use a naming convention of ??????WN.int for these programs.

  • CBL_ functions are platform independent. For example to delete a file you could use CBL_DELETE_FILE.

  • Never store COMP-5 fields in data files as the format of these fields is processor dependant

  • Never store COMP-5 fields in a datablock for passing data to/from the program/screenset (you can use them as long as they are only used on the client)

The Unix compiler is more sensitive to certain source code whereas Net Express is more forgiving. The following areas should be coded more carefully to ensure that you programs compile on both platforms:

  • STRING - you must have a DELIMITED BY clause after each and every field

  • SET - you must SET an object reference to another one - do not use MOVE

  • PERFORM - you must have an imperative statement after an in-line perform - the statement CONTINUE can be used as it is a no-operation statement.

Dialog system implications

Generally screensets are platform independent. In addition they always run on the client on a client/server system so Unix is not an issue.

To ensure that you don’t have unexpected client/server issues see the guidelines below.

  • Generally you should avoid creating a datablock field defined as COMP-5. These fields are stored in a processor dependant format and will cause a problem if you attempt to access the value from with a program on some Unix servers. If you only access the field from the client then these fields can be used. This problem will be found on IBM AIX, SUN Solaris, HP UX and other Risc processor based server systems.

    Check you are not passing C5 fields

  • Avoid creating an excessively large datablock as the datablock contents have to be sent between the client and server.

  • Avoid excessive use of RETC. Every time you use RETC the datablock has to be sent from the client to the server (and usually back again). For example if you have 4 validation functions on a dialog box consider a consolidated one that tests all 4 validations. This is useful when the operator clicks on ‘Save’ or ‘OK’.

  • If the datablock contains a relatively large table place this table immediately before the field S-END. The client/server optimization will ensure that this will give the best level of performance as most of the time the end of the table will be empty or unchanging.

  • Consider setting the mouse pointer to an hour glass immediately before a RETC. On some systems the function may take some time and this helps the operator realise that the system is still working.

  • Remember that on WAN environments a single RETC could take half a second to a full second depending on the environment. Satellite systems often have a 0.6 second delay.

Deployment considerations

When deploying systems to a client/server environment – whether Windows NT or Unix - remember the following:

  • The program will be running on the server.

  • The Screenset (and any user-controls) will be running on the Client

  • By defining a custom program and screenset directory on the server and installing the latest copies of your software into these directories the screensets will be transferred to the appropriate client system when required. This transfer is activated when:

    • There is a customized screenset on the server

    • The size of the screenset on the server is different from the size of the screenset on the client or alternatively there is a VERGUI.TXT file in the screenset directory on the server that differs from the VERGUI.TXT file sitting in the client's screenset directory.

    • In addition to the screenset any user-control programs will be transferred from the ‘bin’ sub-directory. These are the programs that control listview and toolbar objects.

    • See the Deploying custom screensets topic for an example about how to deploy your screensets and user-controls for this up-load feature.

Setting up a system for Unix Deployment

If you require to deploy your programs on a Unix environment there are some support files to assist in this process. These are installed into \rnd60\source\unix as part of the SYSPRO SDK.

The important difference between deploying on Unix and deploying on a Windows platform is that on Unix the (older) COBOL 4.1 run time system is used. This is the same version used by Encore 3.2/4.0. On Windows platforms SYSPRO uses the (newer) Net Express 3.1 run time system.

The reason for not using the later ServerExpress product which would give intermediate code compatibility is that ServerExpress is not available on some of our existing deployed platforms such as SCO OpenServer.

Due to this difference you cannot simply copy intermediate code programs created on Windows with Net Express and use them on Unix. You will receive an error 9-161 or an Intermediate code missing or corrupted or similar error message.

There are basically two ways of compiling programs for a Unix Client/Server target platform.

Compile on Unix

This is the method used by Syspro when creating a Unix distribution CD. This requires a Unix compiler for COBOL 4.1 (the one used for Encore 3.2/4.0). You then need to:

  • ftp your source code (and copybooks) to the Unix platform (use the ASCII) setting

  • compile your programs on Unix – see the directives below

  • use the intermediate or native code generated

This is the recommended method as the Unix compiler generates intermediate code for the correct platform and if you need native code (.gnt) programs these can be created.

Note that the COBOL compiler on Unix may be more restrictive about the Syntax allowed and you may need to adjust your source code to avoid certain coding.

The following directives are used to compile under Unix. You can place these in a file called cobol.dir.

NOCONFIRM

OLDREADINTO

INTLEVEL"2"

NODETECTLOCK

NOANIM

FILETYPE"1"

COMP

NOALTER

BOUND

OMF(GNT)

NOQUAL

SPZERO

MFOO

OOCTRL(+P)

REMOVE "HEADING"

REMOVE "GROUP"

REMOVE "REPORT"

REMOVE "DE"

REMOVE "CF"

Compile on Windows and ftp the intermediate code to Unix

This technique can often prove successful and avoids the requirement of a Unix compiler for the target platform.

Do not use this technique where:

    • You require native code (.gnt) programs

    • You are receiving intermediate code errors when running your programs on Unix

However in most cases this technique does prove successful.

To setup a system to compile Unix programs on your Windows platform your should:

    1. Ensure you have the COBOL 4.0.38 compiler (or above) installed on your Windows system. This is the 32 bit compiler used for Encore 3.2/4.0

    2. Load a DOS prompt and change to \rnd60\source\unix

    3. Edit the file COMPUSET.BAT to ensure that the PATH and COBDIR environment variables point to the appropriate COBOL 4.0 directories

    4. Run the batch file COMPUSET to set the variables

    5. Copy your source code (.cbl only) to the \rnd60\source\unix directory

    6. Compile the program using the COMPUNIX batch file. For example if your are using the program SDKQRY then enter

      COMPUNIX SDKQRY

      This creates a program called \rnd60\source\unix\prgunix\SDKQRY.int

    7. ftp this intermediate code to your Unix platform using the binary setting
      Ensure that the program has the correct lower-case extension (e.g. SDKQRY.int)

    8. Test your newly created program (for example enter File, Run, SDKQRY)

      If your program is not found:
      - Ensure that it is installed in the correct directory
      - Ensure that it has a lower-case extension

      If your program fails with Error 9-161 or another error indicating an intermediate code load failure or error when it loads then you may need to compile the program on the target Unix platform as mentioned above.

See also

Deploying custom screensets, EXECUTE-COMMAND-ON-SERVER, EXECUTE-COMMAND-ON-CLIENT


Debugging on Unix

Introduction

During the development cycle most programmers use a standalone Windows system as it allows you to use the Net Express IDE to edit your code, compile and animate your programs.

When coded appropriately your programs will also work in a Windows server Client/Server system and a Unix server Client/Server system.

The remainder of this article introduces you to the process of debugging your Unix server programs. This assumes that your programs already works successfully in a Windows server based environment but is giving problems in a Unix server environment.

Your programs do not compile on Unix

Note that from SYSPRO 6.1 you do not need to compile your programs on Unix - simply use ftp to binary transfer the object code (INT) from Net Express. The remainder of this topic is only relevant when using SYSPRO 6.0 and prior versions. The sub-topic about debugging a program that crashes or hangs on Unix is still relevant.

The following lists some of the common problems when compiling a program on Unix that previously compiles successfully on Windows.

Case sensitive file names

Remember that your source code file name should typically be uppercase. For example:

INVPEN.CBL

Unknow copy file

Also copybooks referenced in your source code should also be in uppercase. See the sample code fragment for a correct program:

LINKAGE SECTION.

COPY "LINK.WRK".

PROCEDURE DIVISION USING LINK, LINK2.

COPY "PROBEGIN.PRO".

Compiler directives

Unknown data description qualifier OBJECT

The compiler directives should be defined in a file called cobol.dir (exact case). If this is not found the you can receive various errors (like this one) when compiling your code.

Syntax differences

As we currently use the older COBOL compilers on Unix some of the syntax checking is different to the Windows Net Express checking. The following issues relate to these differences:

STRING without delimited by phrase

When using a STRING statement you must add a DELIMITED BY phrase after each string fragment. For example:

STRING

"Stock code '" DELIMITED BY SIZE

INVMST-STK DELIMITED BY " "

"' not found." DELIMITED BY SIZE

INTO LINK-EXTRA.

PERFORM must have an imperative statement

When using an inline PERFORM Unix requires an imperative statement. In the example below the CONTINUE verb is a 'no operation'.

For example the following:

PERFORM VARYING XX1 FROM 1 BY 1 UNTIL STOCK-CODE(XX1:) = SPACES

END-PERFORM.

Should be re-coded as:

PERFORM VARYING XX1 FROM 1 BY 1 UNTIL STOCK-CODE(XX1:) = SPACES

CONTINUE

END-PERFORM.

SECTION out of sequence and similar

The Unix compiler is more strict about the sequence of DIVISIONS and SECTIONS.

For example the CLASS-CONTROL SECTION must be defined in the FILE-CONTROL SECTION. See the following code fragment of a correct program:

FILE-CONTROL.

COPY "ADMREP.SEL".

COPY "CLASS.WRK". *> Contains CLASS-CONTROL

.

DATA DIVISION.

FILE SECTION.

COBOL word contains more that 30 characters

The maximum length of any field name or paragraph name is 30 characters.

Operand D-DATA-BLOCK not defined

Remember to take the screenset copybook (CPB) file after you have compiled it using the COMPILE batch file. This replaces the file name prefix with 'D'. This is not a Unix issue but is an easy mistake to make.

Debugging a program that crashes or hangs under Unix

The following lists some of the common issues when your program has compiled and runs on Unix but either generates a CCI error or hangs but works fine on a Windows Client/Server environment.

File handling

Unix file names are case sensitive on Unix

  • When opening files you must ensure that you have the correct case (both path and file name)

  • When creating files you must ensure that you are using an appropriate case-sensitive file name

Unix file names cannot be spacey

  • Unix does not support spacey file names and therefore all spacey file names must be renamed. If in doubt use underscores to replace embedded spaces.

  • Do not attempt to use quotes (single or double) around file names as the quotes are treated as part of the file name

Unix ISAM files have different extensions

  • Data file names do not have any file extension - e.g. the Inventory master file is named ?INVMST - where ? is the company id. The normal functions to build file names cater for this however any code you develop to parse a file name must allow for this difference.

  • Index file names have a lowercase '.idx' extension - e.g. the Inventory master file index is named ?INVMST.idx.

Unix paths are different

  • Unix uses '/' as the folder separator

  • Use the field LINK-OS-SLASH for server based paths. This contains '/' or '\' depending on the server operating system.

  • You should hard code the use of '\' for client based paths as they are always Windows (do not use LINK-OS-SLASH for client paths).

  • Do not assume a drive as Unix does not have drive letters

  • Do not assume files have dots - many Unix files do not contain dots

  • File names such as '.profile' are perfectly valid and quite common (note there is no part before the dot and a longer that 3 character extension)

The CBL_ functions must be coded in uppercase

The Net Express functions that begin CBL_ are platform independent. However they must be coded in uppercase - e.g. CBL_TOLOWER and CBL_TOUPPER

  • Note that there are equivalent SYSPRO functions for some of these CBL_ routines.

  • CONVERT-UPPER-CASE (converts to all uppercase)

  • CONVERT-LOWER-CASE (converts to all lowercase)

  • CONVERT-UPPER-LOWER (converts to initial letter uppercase and rest lowercase)

ASCII files have different line delimiters

Unix ASCII files (LINE SEQUENTIAL) use a single line feed (X"0A") character to delimit a line of text whereas Windows files use carriage return line feed pair (X"0D0A")

  • When copying an ASCII file to/from a Unix server it is important to use the appropriate ASCII copy function.

  • COPY-FILE-TO-SERVER-ASCII

  • COPY-FILE-TO-CLIENT-ASCII

  • Note in SYSPRO 6.1 both of these functions handle any size ASCII file

  • Note that when using these functions on a Windows server based system these functions perform a binary copy as there is no requirement for any translation. Therefore when transferring ASCII files you should use these functions regardless of the server O/S.

You must not use COMP-5 fields in the data block

COMP-5 fields are numeric values that are stored differently depending on the type of processor architecture. Intel processors used for all Windows platforms and SCO Unixware, SCO Openserver, Linux etc stores numeric values in one style whereas RISC processors (HP, AIX etc) store them differently.

If you are having an issue on one of the RISC processors only then you have probably used COMP-5 values incorrectly.

  • You must not use COMP-5 fields in the data block when these values are being passed from server to client or back again

  • It IS acceptable to use COMP-5 fields in the data block when the values are used in a user-control program and only referenced by a screenset.

Perform nested too deeply

Branching out of a PERFORM using a GO TO is not good programming practice as it consumes the perform stack. The maximum depth of PERFORM nesting varies from O/S to O/S and by experience is much lower on Unix based systems.

  • Avoid using a GO TO within a PERFORM to break the nesting structure

  • If your program appears to be crashing on Unix and it works on Windows check the code for possible GO TO out of PERFORMS

Excessive record locks

When using READ-LOCK or READ-WAIT or similar ISAM statements a record lock is acquired. You should ensure that you do not consume an excessive number of record locks. The maximum number of locks supported is different from platform to platform and can be affected by operating system tuning parameters, versions and available memory.

We have had instances where an incorrectly coded program attempted to read all records in a file - but inadvertently locked them all. On some platforms this worked 'fine' (was slower than expected but did not fail). however on other platforms (e.g. SCO Openserver) a run-time error was returned and the process hung/crashed. The fix is to ensure that an 'excessive' number of locks is not acquired.

Other Unix related issues

When debugging programs that crash or hang it can be difficult to ascertain how far the code has reached before the problem occurred. The following few ideas can help this debug process.

PERFORM INVOKE-MESSAGE-BOX

  • Use PERFORM INVOKE-MESSAGE-BOX to display messages in the code before and after key events in the program. Move an appropriate message to LINK-EXTRA before displaying the message box. Remember that if your code is already using LINK-EXTRA to save/restore it before using it.

  • You can add this code for debugging only by using the Diagnostic field. See the following code fragment:

IF LINK-DIAGNOSTIC = "debug1"

MOVE "I got here" TO LINK-EXTRA

PERFORM INVOKE-MESSAGE-BOX.

PERFORM OUTPUT-DEBUG-LOG

  • Use PERFORM OUTPUT-DEBUG-LOG to output messages to a log file before and after key events in the program. Move an appropriate message to LINK-EXTRA before outputting the log. Remember that if your code is already using LINK-EXTRA to save/restore it before using it.

  • The OUTPUT-DEBUG-LOG function creates a file on the server called {operator}.TXT in the base folder for Unix and base\settings folder on Windows.

  • The log file (e.g. ADMIN.TXT) contains the date and time that the line was output so that it can be useful to debug long running processes to see how long each part of your program is taking.

  • You can add this code for debugging only by using the Diagnostic field. See the following code fragment:

IF LINK-DIAGNOSTIC = "debug1"

MOVE "I got here" TO LINK-EXTRA

PERFORM OUTPUT-DEBUG-LOG.

See also

CONVERT-UPPER-CASE, CONVERT-LOWER-CASE, CONVERT-UPPER-LOWER, COPY-FILE-TO-SERVER-ASCII, COPY-FILE-TO-CLIENT-ASCII, INVOKE-MESSAGE-BOX, OUTPUT-DEBUG-LOG


Developing for 800 x 600 Resolution

Note that this Article is aimed at SYSPRO 6.0 issue 009 and prior versions. See the Topic Developing for 1024 x 768 Resolution for SYSPRO 6.0 issue 010 and later.

Introduction

SYSPRO 6.0 is designed to be used on a Windows terminal with at least 800 x 600 resolution (knows as Super VGA or SVGA).

SYSPRO 6.0 will work on terminals with higher resolutions. In many cases windows in SYSPRO programs can be stretched to take advantage of the extra real estate that this provides. For example to be able to view more items on the main menu or browses to show more columns of information.

However it is important when developing SYSPRO 6.0 applications to ensure that your user-interface works successfully in the basic 800x600 environment.

You may find it useful to read the topic about the IMPCENTR program for more information about the parameters available.

Setting up Windows

When designing your user-interface using the Dialog System it is important to develop the Windows and Dialog boxes to fit into the basic 800x600 space.

There are a few ways in which this can be done:

  • You can use the 'Settings' Tab of your Windows desktop properties and set the Screen resolution to '800 by 600 pixels'. This will set your entire Windows system to 800x600. Whilst this will replicate exactly what an operator would see it, can limit the usability of Windows while editing your screenset.

  • Alternatively you can leave your Windows desktop properties to a higher screen resolution and use a desktop graphic image to clearly identify the area of the screen that 800x600 operators can use. See below.

Applying a sample 800x600 image to your desktop

There is a graphic image called SDK800.JPG provided as part of the Software Development Kit (from SYSPRO 6.0 issue 009 onwards) that is designed to be used for this purpose. See the following steps:

  1. Edit your Windows desktop properties and select the 'Desktop' Tab. Use the browse button to find and select the image SDK800.JPG (look in the \RND60\SOURCE folder).

  2. Ensure the 'Position:' setting is selected as 'Tile' or 'Center' - Do not leave this as 'Stretch'.

  3. Click OK

This will provide a simple grey desktop with the 800x600 area clearly marked.

It is recommended that you minimize/close other windows while using your system with the desktop marked area to keep it clearly visible.

Best Practices for Developing in an 800x600 Environment

When creating Windows or Dialog boxes ensure that they all fit inside the 800x600 area as described above.

Saving/Restoring Window Position and Size

In addition to ensuring that the initial size and position of the window/dialog box fits within the 800x600 area, the initial window/dialog box shown by each program should generally use the standard function to center/restore the screenset position. The following code is typically defined in Global dialog:

SCREENSET-INITIALIZED

MOVE "END" S-END

MOVE "@(#) 6.0.000" S-SCREENSET-VER

IF= S-TO-MSG "STD Scrtst" END-SCREENTEST-PROC

*

CREATE-WINDOW WIN-MAIN

MOVE-OBJECT-HANDLE WIN-MAIN S-CTR-WINHAN1

MOVE "CentRes" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

The four lines in bold indicate the code to create (but not show) the window and then call a standard function to center the window/dialog box based on the current screen resolution. If the operator has previously loaded the program and the initial window was moved/resized (or dialog box moved) then this will restore the position and/or size that was last defined.

To ensure that the last position/size of the window/dialog box is saved you should use the following code fragment:

*

* Escape from program

CANCEL-PROC

MOVE "SavePos" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

MOVE "S-EXIT" S-FR-MSG

RETC

The two lines in bold indicate that the current position and size of the window/dialog box should be saved.

Ensure that Secondary Dialog Boxes are Positioned Correctly

If the screenset makes use of secondary dialog boxes then their properties should have the Option set to 'Relative Positioning'. This means that the dialog box will be positioned relative to where it's parent is positioned.

You should then ensure that when you create and position the dialog box that this will always reside within the 800x600 area. Generally these dialog boxes should be positioned to fit over-the-top of the initial window/dialog box.

Where this is not possible (for example where the initial window/dialog box is quite small) then remember that the initial window/dialog box will be centered in the 800x600 area by default. Position the dialog box appropriately to ensure that they will remain in the 800x600 area when the initial window/dialog box is centered.

Ensure that all dialog boxes are no larger that 800x600

Lastly you should ensure that all dialog boxes are always 800x600 or less in size. As dialog boxes cannot be resized if they are created larger than the 800x600 area an operator using an 800x600 system will not be able to see part of the dialog box.

See also

Developing for 1024 x 768 Resolution, Screen Customization Kit Overview, IMPCENTR - Centre, Save and Restore Window Size and Position


Developing for 1024 x 768 Resolution

Note that this Article is aimed at SYSPRO 6.0 issue 010 and later versions. See the Topic Developing for 800 x 600 Resolution for SYSPRO 6.0 issue 009 and before.

Introduction

SYSPRO 6.0 is designed to be used on a Windows terminal with at least 800 x 600 resolution (knows as Super VGA or SVGA).

SYSPRO 6.0 will work on terminals with higher resolutions. In many cases windows in SYSPRO programs can be stretched to take advantage of the extra real estate that this provides. For example to be able to view more items on the main menu or browses to show more columns of information.

However it is important when developing SYSPRO 6.0 applications to ensure that your user-interface works successfully in the basic 800x600 environment.

You may find it useful to read the topic about the IMPCENTR program for more information about the parameters available.

The remainder of this topic explains how this is done.

History

Until SYSPRO 6.0 Issue 010 we have developed SYSPRO screensets to fit within 800x600 pixels. There are still many of our customers who only have this screen resolution and we want to continue supporting them.

However many of our SYSPRO 6.0 issue 010 screensets are resizable (e.g. the Queries, Order entry etc.)

The operators who have higher resolution screens still have to click and drag the windows to make them larger. This can make our software look a bit odd as everything appears in the top left of their desktop the very first time they run a specific program.

From issue 010

From SYSPRO 6.0 issue 010 we are developing for 1024x768 but still cater for the users with 800x600.

How this works is explained below:

  1. All resizable windows should be designed to fit within 1024x768

    1. This means that the Queries and Posting programs that use the Display and Entry Forms should be resized to fit within 1024x768

    2. Other resizable windows do not have to be made larger to fill the full 1024x768 but you can if it makes sense

  2. All Dialog boxes and non-resizable windows must still fit within the old 800x600.

Note that the program that centres, saves and restores window positions (IMPCENTR) has been changed so that if an operator only has 800x600 and the window is larger then it will be shrunk to fit.

Setting up Windows

When designing your user-interface using the Dialog System it is important to develop resizable Windows to fit within 1024x768 and Dialog boxes and non-resizable windows to fit into the basic 800x600 space.

There are a few ways in which this can be done:

  • You can use the 'Settings' Tab of your Windows desktop properties and set the Screen resolution to 800x600 and 1024x768 as required. However this is awkward when editing multiple screensets.

  • Alternatively you can leave your Windows desktop properties to a higher screen resolution and use a desktop graphic image to clearly identify the area of the screen that 800x600 and 1024x768 operators can use. See below.

Applying a sample 1024x768 image to your desktop

There is a graphic image called SDK1024.JPG provided as part of the Software Development Kit (from SYSPRO 6.0 issue 010 onwards) that is designed to be used for this purpose. See the following steps:

  1. Edit your Windows desktop properties and select the 'Desktop' Tab. Use the browse button to find and select the image SDK1024.JPG (look in the \RND60\SOURCE folder).

  2. Ensure the 'Position:' setting is selected as 'Tile' or 'Center' - Do not leave this as 'Stretch'.

  3. Click OK

This will provide a simple grey desktop with both a 800x600 and 1024x768 area clearly marked.

It is recommended that you minimize/close other windows while using your system with the desktop marked area to keep it clearly visible.

It is best practice when designing a resizable window to fit within the 1024x768 size that you use the small 'angled corner' placed just within the bottom-right edge. This helps people with task bars etc.

Best Practices for Developing in an 1024x768 Environment

When creating non-resizable Windows or Dialog boxes ensure that they all fit inside the 800x600 area as described above.

Sizable windows can be developed up to the 1024x768 size.

Saving/Restoring Window Position and Size

In addition to ensuring that the initial size and position of the window/dialog box fits within the appropriate area, the initial window/dialog box shown by each program should generally use the standard function to center/restore the screenset position.

Dialog box

For a Dialog box or non-resizable window you should use the 'CentRes' function (the case is not important). This function will centre the dialog box in the Desktop and if the position has been previously saved it will be restored to the saved position.

The following code is typically defined in Global dialog for a Dialog box:

SCREENSET-INITIALIZED

MOVE "END" S-END

MOVE "@(#) 6.0.000" S-SCREENSET-VER

IF= S-TO-MSG "STD Scrtst" END-SCREENTEST-PROC

*

CREATE-WINDOW WIN-MAIN

MOVE-OBJECT-HANDLE WIN-MAIN S-CTR-WINHAN1

MOVE "CentRes" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

The four lines in bold indicate the code to create (but not show) the window and then call a standard function to center the window/dialog box based on the current screen resolution. If the operator has previously loaded the program and the initial dialog box was moved then this will restore the position that was last defined.

Window

For a sizable window the 'SizeRes' function should be used instead of the 'CentRes' function as shown below. In this case the last saved position and size is restored if previously saved.

SCREENSET-INITIALIZED

MOVE "END" S-END

MOVE "@(#) 6.0.000" S-SCREENSET-VER

IF= S-TO-MSG "STD Scrtst" END-SCREENTEST-PROC

*

CREATE-WINDOW WIN-MAIN

MOVE-OBJECT-HANDLE WIN-MAIN S-CTR-WINHAN1

MOVE "SizeRes" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

All screensets

To ensure that the last position/size of the window/dialog box is saved you should use the following code fragment:

*

* Escape from program

CANCEL-PROC

MOVE "SavePos" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

MOVE "S-EXIT" S-FR-MSG

RETC

The two lines in bold indicate that the current position and size of the window/dialog box should be saved.

Ensure that Secondary Dialog Boxes are Positioned Correctly

If the screenset makes use of secondary dialog boxes then their properties should have the Option set to 'Relative Positioning'. This means that the dialog box will be positioned relative to where it's parent is positioned.

You should then ensure that when you create and position the dialog box that this will always reside within the 800x600 area. Generally these dialog boxes should be positioned to fit over-the-top of the initial window/dialog box.

Where this is not possible (for example where the initial window/dialog box is quite small) then remember that the initial window/dialog box will be centered in the 800x600 area by default. Position the dialog box appropriately to ensure that they will remain in the 800x600 area when the initial window/dialog box is centered.

Ensure that all dialog boxes are no larger that 800x600

Lastly you should ensure that all dialog boxes are always 800x600 or less in size. As dialog boxes cannot be resized if they are created larger than the 800x600 area an operator using an 800x600 system will not be able to see part of the dialog box.

Preventing the 800x600 warning from appearing

As standard SYSPRO programs require a minimum of a 800x600 resolution desktop - when SYSPRO loads it checks the size of the desktop and displays a warning message if the desktop is not at least 800x600.

However in the case of a completely custom application aimed at a hand held or similar device then this warning may not be required. You can suppress this message by moving the string 'anysiz' (exact case) to the site id defined in the system setup.

See also

Developing for 800 x 600 Resolution, Screen Customization Kit Overview, IMPCENTR - Centre, Save and Restore Window Size and Position


Developing for a COM Environment

Introduction

When developing business objects, or programs that are called by business objects when running in a COM environment, you should be aware of the following:

- You must compile the program with the $set REENTRANT(2) directive

- You may not use the CANCEL verb to cancel a program from memory

- You must define any file names referenced in an ASSIGN clause in WORKING STORAGE.

Each of these points are related to the fact that in a COM environment multiple instances of the program need to be handled by the run-time system. For more details see below.

REENTRANT(2) directive

All e.net business objects, and all programs called by e.net business objects, must have the following directives defined at the top of their source code:

$set REENTRANT(2)

$set CONSTANT REENTRANT-DIRECTIVE(2)

Note that it is not possible to detect at run-time that the program was compiled with the REENTRANT(2) directive. However a constant (in this case called REENTRANT-DIRECTIVE) can be verified at run-time. We use this constant together with a diagnostic option to assist in verifying that all programs were compiled with the REENTRANT(2) directive.

To enable this verification set the Diagnostic option to 'enet03' using the SYSPRO System Setup program. Once the diagnostic has been set to 'enet03' every program run in a COM environment will check that the constant called REENTRANT-DIRECTIVE has been defined. If not an appropriate exception message will be returned indicating the name of the program that has been incorrectly compiled.

See the topic Comment header block for e.net for an example of how to define these directives.

Note that this diagnostic is available from SYSPRO 6.0 issue 008 and later.

Use of the CANCEL verb

When running any program in a COM environment you must not use the CANCEL verb.

All the standard routines (defined in .PRO copybooks) have been changed to ignore CANCEL when running in a COM environment.

In addition a new routine called CANCEL-PROGRAM has been defined in PROBEGIN.PRO. This routine should be used whenever you wish to cancel a program from memory. This routine does nothing in a COM environment.

Defining file names in WORKING STORAGE

All e.net business objects, and all programs called by e.net business objects, must have file names referenced in an ASSIGN clause defined in WORKING STORAGE.

If you hard code a SELECT statement in your source code the ASSIGN clause references a field defining the file name. For example:

*

***************************

** Temporary sort file **

***************************

SELECT USRTMP

ASSIGN USRTMP-DATA

ORGANIZATION INDEXED

ACCESS DYNAMIC

LOCK MANUAL WITH LOCK ON MULTIPLE RECORDS

FILE STATUS IS STAT-CODE

RECORD KEY IS USRTMP-KEY.

In this example the field USRTMP-DATA must be defined in WORKING STORAGE.

Note that by default the compiler will assign a field called USRTMP-DATA for you. This field must not be used in a COM environment as the field can be shared across multiple instances of the object. You must define the field in WORKING STORAGE as follows:

01 USRTMP-DATA PIC X(255).

Note that all standard SYSPRO files (defined in SELECT copybooks - for example INVMST.SEL) have an equivalent file name defined in a copybook called FILE.WRK. Therefore you do not have to create file names in WORKING STORAGE for standard SYSPRO file names.

Also note that several common temporary file names are included in FILE.WRK. See the following code fragment from FILE.WRK.

* File definitions for temporary files

01 TMP-DATA PIC X(256).

01 TMPDAT PIC X(256).

01 TMP1DAT PIC X(256).

01 TMP2DAT PIC X(256).

01 TMP3DAT PIC X(256).

01 TMP4DAT PIC X(256).

01 TMP5DAT PIC X(256).

See also

Comment header block for e.net, CANCEL-PROGRAM, Diagnostic options


Emailing a Document

Introduction

This article covers how you can add the ability to send an email message from within your Net Express program using facilities built into SYSPRO.

Pre-requisites

The end-user system requires that the Office Automation Module is installed

Overview

SYSPRO contains a utility program to perform most of the work of sending an email. The program is called IMPEML.

This program has a linkage defined by the copybook IMPEML.LNK - this is shipped as part of the SYSPRO Software Development Kit. The linkage is designed to be reasonably self-documenting. However in many cases it is easier to see an example. See below.

Code Fragment for Sending Email

The following code fragment demonstrates sending an email message with and without an attachment.

01 LNK2.

COPY "IMPEML.LNK". *> Email linkage

*

LINKAGE SECTION.

COPY "LINK.WRK". *> Standard linkage

01 LINK2 PIC X. *> Dummy 2nd linkage

*

PROCEDURE DIVISION USING LINK, LINK2.

COPY "PROBEGIN.PRO".

*

PERFORM EMAIL-SIMPLE-MESSAGE.

PERFORM EMAIL-WITH-ATTACHMENT.

*

GO TO ENDJOB.

*

***********************************************************

** Build a simple message and send it with no operator **

** intervention **

***********************************************************

EMAIL-SIMPLE-MESSAGE.

INITIALIZE LNK2.

MOVE SEND-MAIL TO IMPEML-MAIL-FUNCTION.

MOVE "MyEmail@za.syspro.com" TO IMPEML-MAIL-RECIPIENTS.

MOVE "Testing Email..." TO IMPEML-MAIL-SUBJECT.

STRING

"This message demonstrates sending " DELIMITED BY SIZE

"Email directly from a SYSPRO " DELIMITED BY SIZE

"program." DELIMITED BY SIZE

INTO IMPEML-MAIL-MESSAGE-TEXT.

MOVE "IMPEML" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

*

**********************************************************

** Build a message and send it with an attachment **

** with no operator intervention **

** Assume attachment is C:\TEMP\TEXT.TXT **

**********************************************************

EMAIL-WITH-ATTACHMENT.

INITIALIZE LNK2.

MOVE SEND-MAIL TO IMPEML-MAIL-FUNCTION.

MOVE "MyEmail@za.syspro.com" TO IMPEML-MAIL-RECIPIENTS.

MOVE "C:\TEMP\TEXT.TXT" TO IMPEML-FILE-ATTACHMENT(1).

MOVE "Report.doc" TO IMPEML-FILE-DESCRIPTION.

MOVE "Testing attachment" TO IMPEML-MAIL-SUBJECT.

STRING

"This message demonstrates sending " DELIMITED BY SIZE

"Email directly from a SYSPRO " DELIMITED BY SIZE

"program with an attachment." DELIMITED BY SIZE

INTO IMPEML-MAIL-MESSAGE-TEXT.

MOVE "IMPEML" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

Notes

You can optionally force the operator to click the Send button (allowing them to make changes before they send the message) by moving SEND-WITH-PREVIEW to the field IMPEML-MAIL-FUNCTION.

The field IMPEML-FILE-DESCRIPTION is often used by the receiving email client software to determine the file association. This affects what program is called when the recipient double-clicks on the attachment.

Client/Server Implications

Note that in a client/server environment the email is sent from the client therefore any file attachments must reside on the client and the path specified must be relative to the client PC. See the function COPY-FILE-TO-CLIENT to transfer a server file to the client PC.

See also

CALL-PROGRAM


General Ledger Line Numbers

Background

Before SYSPRO 6.0 issue 008 the General Ledger system had 5 digit line numbers defined in various files. The line numbers were therefore limited to the values '00000' - '99999' (100,000 values).

An increase in the number of values was required but due to ISAM space limitations the 5 digit numeric line number it was decided to change these to 5 character alphanumeric line numbers from SYSPRO 6.0 issue 008.

Valid line numbers

The valid values are '00000' - '99999' (as before) plus 'AAAAA' - 'ZZZZZ'.

This gives an additional 11,881,376 values. Therefore the total number of available line numbers is 11,981,376 (approximately 12 million).

The new functions

Two new functions have been developed to allow developers to increment and decrement the 5 character alphanumeric line numbers. These are INCREMENT-LINE-X5 and DECREMENT-LINE-X5.

These new routines take the field WW-LINE-X5 and either increment or decrement the value according to the following logic:

- The valid values are '00000' - '99999' and 'AAAAA' - 'ZZZZZ'.

- When incrementing a value '00000' it will become '00001', then '00002', then '00003' etc.

- When incrementing a value '99999' it will become 'AAAAA'.

- Incrementing a value 'AAAAA' will return 'AAAAB', then 'AAAAC' etc.

- When incrementing 'ZZZZZ' you will receive an overflow error value 'O' in WW-LINE-STAT.

- If you pass a value outside the valid range you will receive an error value 'E' in WW-LINE-STAT.

- An initial value of spaces will be assumed to be '00000'.

The reverse logic is used when decrementing:

- 'ZZZZZ' will become 'ZZZZY', 'ZZZZY' will become 'ZZZZX' etc.

- 'AAAAA' will become '99999'.

- Decrementing '00000' will return the overflow (underflow) value 'O' in WW-LINE-STAT.

Remember when using these fields to store them as PIC X(5) - char(5) and also you should use care when displaying/printing these fields as they are alphanumeric fields.

Sample code

* Increment the next line number in GenMaster

MOVE GENMST-CNXT TO WW-LINE-X5.

PERFORM INCREMENT-LINE-X5.

IF WW-LINE-STAT = "O"

PERFORM MAX-LINE-NUMBER-EXCEEDED

ELSE

IF WW-LINE-STAT = "E"

PERFORM INVALID-LINE-NUMBER

ELSE

MOVE WW-LINE-X5 TO GENMST-CNXT.

See also

INCREMENT-LINE-X5, DECREMENT-LINE-X5


IMPCENTR - Centre, Save, Restore

SYSPRO SDK

Articles

IMPCENTR - Centre, Save and Restoring Windows

Introduction

The IMPCENTR program is a Client side utility that is designed to be called from a screenset (usually against the SCREENSET-INITIALIZED pseudo event in Global Dialog) to save/restore/centre the size and position of a Window or Dialog box.

The basic logic is to create the main window (usually called WIN-MAIN) and call IMPCENTR passing the OBJECT HANDLE and the function required. In addition the screenset should call IMPCENTR when it exits to save the current size and position of the Window or Dialog box for subsequent restoring.

See the topic Developing for 1024 x 768 Resolution for more information about best practices in using these functions.

A typical program that has a Window with a sizable border will use the following code in SCREENSET-INITIALIZED.

SCREENSET-INITIALIZED

MOVE "END" S-END

MOVE "@(#) 6.0.000" S-SCREENSET-VER

IF= S-TO-MSG "STD Scrtst" END-SCREENTEST-PROC

*

CREATE-WINDOW WIN-MAIN

MOVE-OBJECT-HANDLE WIN-MAIN S-CTR-WINHAN1

MOVE "SizeRes" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

*

etc...

In addition the CANCEL-PROC function will have the code to save the window position and size. See the following code fragment.

CANCEL-PROC

MOVE "SavePos" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

MOVE "S-EXIT" S-FR-MSG

RETC

And SCREENSET-POSITION-PROC is defined as follows:

SCREENSET-POSITION-PROC

CLEAR-CALLOUT-PARAMETERS $NULL

CALLOUT "impcentr" 3 $NULL

The information about the size and position of the Window or Dialog box is stored in a file called ADMWIN.DAT/IDX using the operator code and screenset name as the key.

A typically SYSPRO program only stores the size/position of WIN-MAIN. Any other Dialog boxes defined in the same screenset are shown relative to WIN-MAIN. However there are times when you may wish to save/restore/centre a subsequent Window/Dialog box in the same screenset. In this case you can move a non-blank value to the field S-FR-PAR before any of these functions - this is moved to the field 'ADMWIN-SCREEN-NAME' in the key below. Blank means the primary Window.

The full key of ADMWIN.DAT is defined as follows:

** Note that this file resides in the Client's SETTINGS

** sub-directory

01 ADMWIN-REC.

03 ADMWIN-KEY.

05 ADMWIN-OPERATOR PIC X(12).

* Operator code

05 ADMWIN-SCREENSET PIC X(12).

* Screenset name

05 ADMWIN-SCREEN-NAME PIC X(30).

* Screen name

Only the first 6 characters of the operator code and screenset name are currently used.

If you use a non-blank S-FR-PAR to define a second or subsequent window remember that you may need to save all these values when the program exits.

Note: None of the IMPCENTR functions have any effect if the Options, Customize function from the SYSPRO menu (Workspace Tab) checkbox labeled 'Save primary window settings upon exit' is unchecked.

IMPCENTR functions

The following section documents the functions available. All function names are case insensitive.

'Center' or 'Centre'

This function centres the Window or Dialog box on the current Desktop. It does not attempt to resize windows with the 'Size border' option set.

As an example the very first splash screen in SYSPRO uses the 'Centre' function. See the following code fragment from this program.

CREATE-WINDOW WIN-MAIN

MOVE-OBJECT-HANDLE WIN-MAIN S-CTR-WINHAN1

MOVE "Center" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

Input parameters:

S-FR-MSG - Function name

S-FR-PAR - Window name (blank means WIN-MAIN)

S-CTR-WINHAN1 - Window/Dialog box handle

'CentRes'

This function attempts to restore the current position (but not size) of the Window or Dialog box on the desktop. If the Window/Dialog box has not been saved from a previous session then the Window or Dialog box will be centred on the Desktop exactly the same as if the 'Center' function had been used.

This function is designed to be used for Dialog boxes and 'non-sizable' Windows. From SYSPRO 6.0 issue 010 it is recommended that the size of the Window/Dialog box is a maximum of 800x600.

See the topic Developing for 1024 x 768 Resolution for more information about best practices in using this function.

Most SYSPRO reports (such as the A/R Trial Balance) use this function. See the following code fragment from this program:

CREATE-WINDOW WIN-MAIN

MOVE-OBJECT-HANDLE WIN-MAIN S-CTR-WINHAN1

MOVE "CentRes" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

Input parameters:

S-FR-MSG - Function name

S-FR-PAR - Window name (blank means WIN-MAIN)

S-CTR-WINHAN1 - Window/Dialog box handle

'SizeRes'

This function attempts to restore the current position and size of the Window on the desktop. If the Window has not been saved from a previous session then the Window will be centred on the Desktop exactly the same as if the 'Center' function had been used.

This function is designed to be used for Windows with a sizable border only.

From SYSPRO 6.0 issue 010 this function caters for any size Window. If the Window is larger than the Desktop then it will be shrunk to fit within the Desktop. For example if the programmer designs the screenset for 1024x768 resolution to provide the best view of information the end-user can use this screenset on a 1024x768 or higher resolution and they will see the original screenset designed. However if the operator uses 800x600 (the minimum required resolution for SYSPRO) then the Window will be shrunk to fit.

See the topic Developing for 1024 x 768 Resolution for more information about best practices in using this function.

Most SYSPRO programs (such as the Inventory Query) use this function. See the following code fragment from this program:

CREATE-WINDOW WIN-MAIN

MOVE-OBJECT-HANDLE WIN-MAIN S-CTR-WINHAN1

MOVE "SizeRes" S-FR-MSG

EXECUTE-PROCEDURE SCREENSET-POSITION-PROC

Input parameters:

S-FR-MSG - Function name

S-FR-PAR - Window name (blank means WIN-MAIN)

S-CTR-WINHAN1 - Window/Dialog box handle

'SavePos'

This function saves the current window position in the ADMWIN file for later use with 'CentRes' or 'SizeRes'.

Input parameters:

S-FR-MSG - Function name

S-FR-PAR - Window name (blank means WIN-MAIN)

S-CTR-WINHAN1 - Window/Dialog box handle

Important note

From Issue 010 SP1 you should be aware that the 'SavePos' function (after saving the window position and size) moves the window off the visible desktop. See the FAQ below for more information.

Why does my window/dialog box disappear with Issue 010 SP1?

Symptom:

You may notice that when running some of your custom dialog applications that the window (or dialog box) disappears or that the program appears to hang (as the window is not visible).

This only occurs with Issue 010 SP1 screensets.

The problem:

As SYSPRO screensets make more use of objects such as listviews and toolbars the 'unloading' of these when a screenset returns back to the main menu can often leave a white square on the screen for several seconds as the Dialog System destroys the objects before it redraws the underlying screen.

In the worst case this looks very bad and gives a poor impression.

IMPCENTR Background:

When most SYSPRO screensets initially load they call a program called 'IMPCENTR' using a 'SizeRes' function - this centres the Window within the current desktop or restores any previously saved size and position. Dialog boxes make use of a 'CentRes' function which performs a similar function but by centering/repositioning the dialog box as there is no 'resizing' of dialog boxes.

In addition, just before the screenset exits, it should call 'IMPCENTR' with a 'SavePos' function to save the current position (and size for windows) so that it can be restored when the program is next loaded.

IMPCENTR Change:

Our solution to the delay (whilst the Dialog System destroys the objects) is to move the window being destroyed off-the-visible-desktop before it is destroyed. The act of moving the window is very quick and the underlying window refreshed immediately - this gives the perception that the window has been 'deleted' instantly.

In reality the window is moved from the visible desktop instantly and then there is the same delay as before as the objects are destroyed but in practice the perception of the system is vastly improved.

The 'SavePos' function in 'IMPCENTR' has been updated so that just after the size and position of the window has been saved the window is moved off the desktop.

This change was made to the program IMPCEN version 6.0.010

IMPCENTR Change Side Effect:

As a side-effect of the above change any screensets that have been coded incorrectly may need to be changed.

The issue is that as described above when 'IMPCENTR' is called with a 'SavePos' function it moves the window off the visible screen. Therefore you must not use the 'SavePos' function until the window is just about to be deleted.

If you have a screenset where the window disappears then it is likely that you have used the 'SavePos' function incorrectly.

The solution is to recode the screenset so that the 'SavePos' function is only used just before the screenset is cancelled.

Note: Reports are not handled in this way so that they can provide a tickover function and the program can quit the screenset when the report has completed. A report is identified by looking at the main menu treeview for a report icon.

See also

Developing for 1024 x 768 Resolution


Importing and Exporting Text Files

If your import or export is using plain text (i.e. the regular characters A-Z, a-z, 0-9 and the common punctuation characters) then you can use a regular LINE SEQUENTIAL file and OPEN INPUT and READ or OPEN OUTPUT/EXTEND and WRITE.

However if your import file contains special characters (such as TABs) or you wish to include special characters (such as TABs) in an export file then you have to switch off the NULL insertion logic that the Net Express run time system performs by default.

What is NULL Insertion?

LINE SEQUENTIAL files consist of strings terminated by an end-of-record indicator. On Windows the end-of-record indicator is a CR LF pair (X"0D0A"). On Unix the end-of-record indicator is a LF character (X"0a").

Therefore a text file with the two lines:

ABC

DEF

is stored as: "ABC" followed by "X0D0A" followed by "DEF" on Windows. This is 8 characters in total. In fact there can also be a X"0D0A" at the end of the last line too depending on how it was created. This can be represented as follows:

ASCII - A B C CR LF D E F

Hex - 41 42 43 0D 0A 44 45 46

Note that an 'A' is Hex 41 and 'B' is Hex '42 etc.

However imagine that you wished to insert a LF (Line Feed X"0A") character as part of the sequential file (not as the end-of-record delimiter). This could 'confuse' the Net Express run time system with the end-of-record indicator. This is even more obvious if you wish to include the two characters CR LF (X"0D0A") as part of the record!

Net Express handles this dilemma by inserting a NULL (X"00") character before each and every 'special' character. A special character is every character in the range X"00" thru X"1F". This is every character below a SPACE character in the ASCII character set.

Special characters include NULL, TAB, LF and CR. The complete list is shown below - common characters have been bolded.

Dec | Hex | ASCII | Also know as | Description
0 | 00 | NULL | CTRL+@ | Null character (lowest character) - binary zero
1 | 01 | SOH | CTRL+A |
2 | 02 | STX | CTRL+B |
3 | 03 | ETX | CTRL+C |
4 | 04 | EOT | CTRL+D |
5 | 05 | ENQ | CTRL+E |
6 | 06 | ACK | CTRL+F |
7 | 07 | BEL | CTRL+G | Bell (sometimes sounds a short beep sound)
8 | 08 | BS | CTRL+H | Back space
9 | 09 | TAB | CTRL+I | Tab
10 | 0A | LF | CTRL+J | Line feed
11 | 0B | VT | CTRL+K |
12 | 0C | FF | CTRL+L | Form feed (on printer)
13 | 0D | CR | CTRL+M | Carriage return
14 | 0E | SO | CTRL+N |
15 | 0F | SI | CTRL+O |
16 | 10 | DLE | CTRL+P |
17 | 11 | DC1 | CTRL+Q |
18 | 12 | DC2 | CTRL+R |
19 | 13 | DC3 | CTRL+S |
20 | 14 | DC4 | CTRL+T |
21 | 15 | NAK | CTRL+U |
22 | 16 | SYN | CTRL+V |
23 | 17 | ETB | CTRL+W |
24 | 18 | CAN | CTRL+X |
25 | 19 | EM | CTRL+Y |
26 | 1A | SUB | CTRL+Z |
27 | 1B | ESC |  | Escape
28 | 1C | FS |  |
29 | 1D | GS |  |
30 | 1E | RS |  |
31 | 1F | US |  |

Therefore if we wish to write out a line to our LINE SEQUENTIAL file inserting the string 'A' followed by a TAB (X"09") followed by a 'B' - normally represented by:

ASCII - A TB B CR LF

Hex - 41 09 42 0D 0A

Net Express will actually write out the following:

ASCII - A NL TB B CR LF

Hex - 41 00 09 42 0D 0A

Note that before the special character TAB (X"09") is a NULL (X"00").

Similarly when you attempt to read a line that contains the above string the Net Express run time system detects the NULL (after the character 'A' - hex '41') and knows that it must treat the very next character 'as is' (and not as part of the end-of-record indicator). Thus it will return to your FD the 3 characters 'A' followed by a TAB followed by a 'B'.

If you attempt to insert a NULL (X"00") into your file then it is preceded with another NULL (X"00"). Thus a single NULL inserted by you into a exported file will be stored as the 2 bytes X"0000".

To summarize... as Net Express stores a record any special characters (below a space) are prefixed with a NULL. When retrieving records each NULL indicates that the next character is to read 'as is' (and therefore ignores the NULL).

The problem

Unfortunately the side effect of this NULL insertion is that if you wish to export a file (for example to Excel with a Tab delimiter) then additional NULLs will be inserted. This will almost certainly cause the importing application to not understand the file format.

Similarly if you wish to import a file with special characters (e.g. TABs) then they will be ignored by the Run Time System as they are NOT prefixed with a NULL.

How can I prevent the automatic NULL insertion logic?

To change the NULL insertion indicator for a specific file you should perform the following steps:

Compiler directives

At the very top of the source code (before any line except for comments) you must insert the following two compiler directives:

$set FCDREG

$set QUAL

Note that the $ character must be in column 7.

The FCDREG directive indicates that a field named FH--FCD will be generated for each file defined in the SELECT clause. However as the field name (FH--FCD) is the same for each file you must allow qualified data names else you will have duplicate field if there are two or more files in your source code. In SYSPRO 6.1 onwards this is enabled by the standard SYSPRO directives - however SYSPRO 6.0 Issue 010 SP2 and prior versions require the QUAL directive to be applied. This enables qualified data names.

Working storage

Add the following two picture strings anywhere in working storage.

01 STATUS-TYPE-NO-NULL PIC X VALUE X"FD".

01 STATUS-TYPE-NEW PIC X COMP-X.

* Fields for checking if

* NULL insertion is set

Linkage section

Add the following copybook to your linkage section (usually just below LINK.WRK).

COPY "IMPFCD.WRK".

Open the line sequential file

If importing a file open the line sequential file INPUT, If exporting then open the line sequential file OUTPUT or EXTEND. For example:

*

MOVE "C:\TEMP\EXPORT.TXT" TO ADMREP-DATA.

OPEN EXTEND ADMREP.

Disable NULL insertion

After checking that the file was opened successfully then you should perform the following code.

*

************************************************

** Turn off nulls before control characters **

** Clear bit 1 in field FCD-STATUS-TYPE **

************************************************

SWITCH-OFF-NULLS.

SET ADDRESS OF FCD-BLOCK TO ADDRESS OF FH--FCD OF ADMREP.

MOVE FCD-STATUS-TYPE TO STATUS-TYPE-NEW.

CALL 'CBL_AND' USING STATUS-TYPE-NO-NULL

STATUS-TYPE-NEW

BY VALUE 1 SIZE 1.

MOVE STATUS-TYPE-NEW TO FCD-STATUS-TYPE.

This code is explained below:

The field FH--FCD is the field exposed by adding the $set FCDREG directive. Appending 'OF ADMREP' indicates that this is the field FH--FCD against the file named ADMREP.

The code that says 'SET ADDRESS OF FCD-BLOCK TO' means that the field FCD-BLOCK defined in the copybook IMPFCD.WRK (in linkage) is to 'redefine' the FCD block of the file ADMREP.

The FCD-BLOCK is a 100 character - X(100) - definition that is used by Net Express to define the file and is used by the Micro Focus File Handler (MFFH.DLL).

The field in the FCD-BLOCK named FCD-STATUS-TYPE is used by the file handler to indicate whether NULL insertion is disabled or enabled. The second lowest bit in this byte is cleared to indicate that NULL insertion is to be disabled. This bit is cleared by using a logical AND with the hexadecimal X"FD".

X"FD" is binary 1111 1101 - note that the second lowest bit is a zero.

Read or write data and handle the special characters as required

Once the SWITCH-OFF-NULLS function has been performed you are ready to read data from the file and it's up to you to cater for the special characters. Similarly you can now write out special characters when exporting.

Close the file

Close the file as normal.

See also

File Status Codes


Language Translation

Introduction

This document provides some best practices you should adopt to ensure that your program works effectively and efficiently in a non-English environment.

There is also a section below that describes a set of server-side translation functions that can be used when required.

After this section a summary of how the Language Translation system works has been provided to assist with your understanding.

Best Practices for using and displaying text

The majority of text that is displayed in a typical SYSPRO application is defined and displayed using the Dialog system when creating your screenset.

The following types of Net Express object can all contain text.

- Windows and Dialog boxes (Headings)

- Tab control (Tab names)

- Push buttons, radio buttons and check boxes

- Group boxes

- Entry fields (with initial text defined)

- Text objects

- Message boxes (Headings and text)

The Language Translation system will automatically translate the text on all these types of objects without you having to perform any additional functions.

However there are some best practices that will assist the Language Translation system in providing a more complete translation of English text.

The system ships with a set of Language Dictionaries, one for each Language. Only words and phrases defined in these Dictionaries will be translated by the system. Any phrase that the system cannot translate will remain in the original English.

Consistency

Consistency in the use of words and phrases improves the likelihood that the Language Translation system already has the word or phrase in it's Dictionary. It is recommended that, where appropriate, you use the same words and phrases that have already been used in SYSPRO.

Any phrase that does not already exist in the Dictionary will appear un-translated (i.e. in English).

Consistency - Punctuation

To help with the consistency of translation it is recommended that any messages that end in a period or question mark do not have any spaces before the period/question mark.

In addition any commas, semi-colons or colons should not have preceding spaces and should be followed by exactly one space.

For example the phrases:

Ok to continue?

You have exceeded your credit limit.

Purchase orders, Sales orders and Jobs exist for this item.

are preferred over the following:

Ok to continue ?

You have exceeded your credit limit .

Purchase orders , Sales orders and Jobs exist for this item.

Object spacing

For regular Windows and Dialog boxes it is recommended that you allow a little extra space after each prompt (before an entry field etc). This allows for the fact that some languages are more verbose that others.

For the same reason it is recommended that other objects such as push buttons are made a little larger than required to cater for other languages where longer text may be required.

The general rule when we translate text is to try and use a phrase of the same length or shorter however this is not always practical - especially for shorter phrases.

This is not applicable to other user-controls such as Listview headings, Display Forms and Entry Forms as the system caters for text of variable length.

Text that contains variable data

As soon as you have information from a data file or from a calculated result (variable data) and you wish to embed this in a message you potentially have a problem.

For example the following phrase will cause a problem:

Stock code B100 not found

as clearly you cannot have a foreign language translation for every possible stock code.

The Language Translation system provides a number of features to assist with the problem of variable data - these are explained below.

Variable data - alphanumeric strings in quotes

If you have a variable value that is an alphanumeric string you can enclose the variable data in single quotes - see the following example message:

Stock code 'B100' not found

The system handles this by parameterizing the value in quotes so that the message becomes:

Stock code '%1' not found

and the parameter %1 is stored as 'B100'.

The system looks for the 'parameterized phrase' in the dictionary and, if found, retrieves the translated text. The parameters in the foreign text are then expanded and the new phrase used instead of the original.

The system handles up to 50 parameters in a single string.

Therefore as long as you enclose alphanumeric variable data in quotes there is nothing else for you to do.

Variable data - numeric values

Numeric values are automatically parameterized - see the following example message:

You have exceeded your credit limit by 1000.00 - function cancelled.

The system handles this by parameterizing the numeric value so that it becomes:

You have exceeded your credit limit by %1 - function cancelled.

and parameter %1 is stored as 1000.00

The system then looks up the parameterized phrase in the Dictionary and retrieves the translated text. The parameters in the foreign text are then expanded and the new phrase used instead of the original.

The system handles up to 50 parameters in a single string.

Variable data - colon + space

Occasionally you may have messages that look as follows:

Operator: ADMIN - System Administrator

Where you have a message followed by a colon + space (': ') and then some variable data.

The system handles this by looking for a colon + space and then remembering the value from the colon onwards. It then removes this from the original phrase and looks up the Dictionary. In the above example the word 'Operator' is found in the Dictionary and then the original phrase from the colon onwards is re-applied.

Text not requiring translation

There are times when you do not want the Language translation system to translate text. For example if you are displaying a file name. In this case you can just display the file name as normal however the system will use it's logic to attempt to translate this file name.

If required you can prefix any text with two colons ('::'). This causes the Language translation system to ignore any translation and to remove the two colons.

For example if you have a file name to be displayed you could add the following logic to force the Language translation system to ignore translation of the file name.

MOVE SPACES TO D-FILE-NAME.

STRING "::" DELIMITED BY SIZE

FILE-NAME DELIMITED BY SIZE

INTO D-FILE-NAME.

Dummy text not requiring translation

There are times when you always replace a piece of text with some other value and therefore whatever text you define is always irrelevant - alternatively you may create a dummy Window, Dialog box or Message box and want to ensure that the text is not passed through the translation logic.

Any phrase that starts with the word 'Dummy' (any case) is ignored from the Language Translation system.

For example if you have to create a dummy screenset (i.e. it is never called) then it's Window title could be:

Dummy Screenset for SDK999

How to handle more complex phrases

The automatic handling of variable data explained above means that the majority of phrases are translated seamlessly (as long as you enclose alphanumeric variable values in quotes and a colon + space is used to indicate that the rest of the phrase is not to be translated).

However you may have a situation where you wish to translate the text yourself.

This can be done as follows:

Translating text from a screenset

You can call the Language Translator on the Client directly from a screenset allowing you to translate up to 255 characters of text.

See the following fragment of dialog where english-text is the field to be translated.

move "TRAN-255" s-fr-msg

move english-text s-fr-par

callout "IMPNLSW1" 3 $null

move s-fr-par foreign-text

move " " s-fr-par

Note that all the variable data parameterization described previously is provided using this function.

Translating Tooltips from a screenset

You can call the Language Translator on the Client directly from a screenset allowing you to translate Tooltips. Tooltips are null terminated strings so need to be handled differently from normal text.

Tooltips applied to toolbars, listviews, entry and display forms are automatically translated. The ToolTips mentioned here apply to the legacy style ToolTips that can be applied to a push button (such as a Multimedia button). From SYSPRO 6.1 onwards we use very few of these style ToolTips.

See the following fragment of dialog where io-text-buffer(1) is a null terminated string to be translated.

move "TRAN-TIP" s-fr-msg

move io-text-buffer(1) s-fr-par

callout "IMPNLSW1" 3 $null

move s-fr-par io-text-buffer(1)

move " " s-fr-par

Concatenating strings

Whilst not directly related to the Language Translation process you may wish to concatenate strings in your screenset to provide better messages. This can be done as shown below.

move "STRING-NS" s-fr-msg

move "Stock code:" s-fr-par

move "B100" s-fr-ext

callout "IMPNLSW1" 3 $null

move s-callout-par msg-text

In the above example the resultant string is:

Stock code:B100

Note that no spaces are inserted between the two strings. There is a similar function called 'STRING' that ensures a single space is inserted between the two strings. For example:

move "STRING" s-fr-msg

move "Stock code:" s-fr-par

move "B100" s-fr-ext

callout "IMPNLSW1" 3 $null

move s-callout-par msg-text

In this case the resultant string is:

Stock code: B100

Translating text from a user-control

You can call the Language Translator on the Client directly from a user-control allowing you to translate up to 600 characters of text.

See the following fragment of code where english-text is the field to be translated.

move "TRAN-600" to d-s-fr-msg.

move english-text to d-data-block(11:600).

move " " to d-s-error.

call "IMPNLSW1" using d-data-block.

move d-data-block(11:600) to foreign-text.

Note that all the variable data parameterization described previously is provided using this function.

Reloading the dictionary

You can force the Language Translation system to reload the current dictionaries. This is useful where your application has create a new Dictionary or edited the current one and wishes the changes to take effect immediately.

The dialog to reload the dictionary is:

move "RELOAD" s-fr-msg

callout "IMPNLSW1" 3 $null

Note that this does not affect any object that has already been shown on your instance of SYSPRO.

Do not try and build a foreign phrase one or two words at a time

A common mistake is to try and join phrases that have already been translated. For example suppose you want to generate an error message as shown below:

The function is not available when the status is Complete.

where the phrase 'Complete' is being appended to the phrase 'The function is not available when the status is'.

This may seem like a good idea as you can translate the first part once and if there are, say 8 statuses, then it appears that only the 8 status messages themselves have to be translated (not the whole phrase 8 times).

The problem is that as you are trying to build up a sentence the syntax of the foreign language may mean that the initial part of the phrase has to be modified due to the use of the final status message.

In this example it is better to translate the whole phrase (there would be 8 of them) or even a better idea is to construct it differently so that it does not form a sentence.

For example

The function is not available with the current status.

Current status: Complete

You can see that in this example the English text (excluding the status description 'Complete') can be translated and will be correct regardless of the actual status.

Screenset Tooltips

Programs that have bitmapped buttons such as Multimedia usually have a Tooltip explaining the usage of the button and any shortcut - for example:

Play Multimedia (Ctrl+P)

Until now the Dialog to handle this is quite lengthy. From SYSPRO 6.0 issue 010 it's much simpler as described below. Note that from SYSPRO 6.1 this technique is rarely required or used.

Against the Window where the bitmapped buttons reside define the following dialog.

WINDOW-CREATED

MOVE-OBJECT-HANDLE PB-EDIT WINDOW-HANDLE(1)

MOVE "Edit Multimedia (Ctrl+E)" IO-TEXT-BUFFER(1)

NULL-TERMINATE IO-TEXT-BUFFER(1)

EXECUTE-PROCEDURE SETUP-TIP

*

MOVE-OBJECT-HANDLE PB-PLAY WINDOW-HANDLE(1)

MOVE "Play Multimedia (Ctrl+Y)" IO-TEXT-BUFFER(1)

NULL-TERMINATE IO-TEXT-BUFFER(1)

EXECUTE-PROCEDURE SETUP-TIP

The procedure SETUP-TIP is usually defined in global dialog and should have the following content.

SETUP-TIP

CLEAR-CALLOUT-PARAMETERS $NULL

CALLOUT-PARAMETER 1 WINDOW-HANDLE(1) $NULL

CALLOUT-PARAMETER 2 IO-TEXT-BUFFER(1) $NULL

CALLOUT "IMPACTW8" 3 $PARMLIST

The program IMPACTW8 will translate the text (if required) and create a Tooltip so that when the mouse is moved over the object the tip is shown.

Translating text from server-side code

The Language Translation system that forms part of SYSPRO 6.1 typically provides translation of user interface elements. This system works with the client-side dictionary loaded when you first connect to SYSPRO.

However there maybe times when you need to apply server-side translation.

There is a function called TRANSLATE-TEXT that allows you to translate a single phrase from server-side code.

Similarly there is a set of functions (TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-LIST and TRANSLATE-TEXT-GET) that allow you to define a list of phrases to be translated and to retrieve the phrases once they have been translated.

Please read the remarks against these functions. If you simply wish to translate parts of the user interface then you should rather use the other language translation functions as they have been highly optimized for performance. Using these 'TRANSLATE-TEXT' functions will typically be slower that the client-side translation technology described in the rest of this topic.

How the language translation system works

The Language Translation system that forms part of SYSPRO 6.1 is designed to provide a number of features to developers and end-users.

Plain Text Dictionary

The Language Dictionaries are shipped as plain text files in the base folder - one file for each language.

The Dictionary files consist of three types of line:

1. Comments that begin with a semi-colon (';')

2. English phrases that begin with a colon (':')

3. Foreign translated phrases that being with a greater-than ('>')

See the following fragment from the French Dictionary.

; SYSPRO translation file

; =======================

; Language : FR - French

;

; Pairs of lines starting

; ':' English text and

; '>' Translated text

;

:Customer

>Client

:Customer / Stock code cross reference required

>Renvoi code stock/client requis

:Customer Address

>Adresse client

:Customer Amendment Journal

>Journal des modifications clients

:Customer Classes

>Classes de clients

:Customer Code

>Code client

Each English phrase is expected to have a corresponding Foreign translation immediately following it.

Alphabetic Language Codes

Each Language is identified by a two character code using the ISO 693-1 standard. The plain text Dictionary that is shipped with SYSPRO use the Language code as part of their file name.

The standard Language codes, their descriptions and the names of their Dictionaries are:

Language code | Dictionary file name | Description
EN | (not applicable) | English
FR | Lang_FR.TXT | French
ES | Lang_ES.TXT | Spanish
DE | Lang_DE.TXT | German
ZH | Lang_ZH.TXT | Simplified Chinese

These are the Language Dictionaries that are shipped with SYSPRO.

If you require to create and maintain your own Language Dictionary you should use the same naming convention - See the file IMPLNG.IMP for a list of the two character Language codes.

Definition of the Language code

When running SYSPRO the Language code can be defined in one of two ways.

Note that the Language code cannot be defined against the Operator else you have the paradoxical problem where you need to request the Operator code but do no know what language to use for the prompt!

Command line language code

You can define a /Lang= parameter on the command line. For example:

/Lang=FR

This causes the specific instance of SYSPRO to use the defined Language code. This is especially useful where you wish to have two or more shortcuts each with a different Language code.

Command line parameters and Language codes are not case sensitive therefore /LANG=FR and /lang=fr and /Lang=FR are all equivalent.

If you define a /Lang= parameter on the command line it will take precedence over any other Language settings.

System-wide Language code

In many companies a single non-English Language code is required. In this case you can configure a default Language code to be used system-wide. This is configured using the Setup, System Setup program.

This stores an entry in the IMPACT.INI file - for example:

IMPLNG=FR

When SYSPRO loads it reads the IMPLNG= entry and sets this as the Language code unless a command line /Lang= parameter has been defined.

Dictionary Search Path

When SYSPRO loads it determines the current Language code and looks for a file named Lang_??.TXT in the Client Base folder (where ?? is the Language code).

If found this Dictionary is loaded.

In addition it looks for any Dictionary that matches the following pattern:

settings\Lang_??*.TXT

If any Dictionaries are found that match this pattern they are loaded, one at a time, in alphabetical file name sequence. If the same phrase is found in two or more dictionaries then the later one will be used.

This means that you can create your own supplementary Dictionary without having to edit the standard Dictionary. In addition you can override any translation in the standard one, if required.

Client/Server self-healing

On a Client/Server environment the system will attempt to self-heal Dictionaries on the Server to the Client. This is done as follows:

The Client software will determine the file size of the following Dictionary files:

Lang_??.TXT

settings\Lang_??_Custom_Dictionary.TXT

settings\Lang_??_Global_Replace_Dictionary.TXT

It will then pass this information to the server software which will then determine the file size of the same files on the server (if any).

If any of these files exist on the Server - but they do not exist on the Client - they will be transferred to the Client. In addition if the files do exist on both Server and Client but their file sizes are different then they will be transferred from the Server to the Client.

In this way any changes to the Dictionaries are automatically self-healed.

The self-healing process may take a few seconds while the Dictionary is being transferred.

Also note that any other Dictionary files that conform to the file name pattern:

settings\Lang_??*.TXT

except for the files mentioned above will not be self-healed.

Editing Custom Dictionary: Lang_EN_Custom_Dictionary.TXT

The SYSPRO Utilities menu contains a Language Translation menu that has an Edit Custom Dictionary program.

This program provides a simple interface to allow you to view and edit a Custom Dictionary for the current language code.

The Custom Dictionary file that is being viewed/edited is shown in the Window title and exists in the Settings folder. The default file is:

settings\Lang_EN_Custom_Dictionary.TXT

The Custom Dictionary consists of pairs of Original text and New text. The Original text is not case sensitive during the translation process. i.e. the case of the Original text is not used to determine a match when a phrase is to be translated. However when a match is found the New text is output 'as is'.

There is no limit to the number of phrase pairs in this Custom Dictionary.

Note that when you Save any changes to this Dictionary that the Dictionary is reloaded immediately for your current system. Therefore as you exit to the menu and load another program the newly loaded program will already be using the new Custom Dictionary. Other operators will only see these changes when they next Login to SYSPRO.

On a Client/Server system the changes are made to the Server and the new Custom Dictionary is immediately self-healed to your specific Client for the changes to take effect immediately.

Editing Global Replace Dictionary: Lang_EN_Global_Replace_Dictionary.TXT

The SYSPRO Utilities menu contains a Language Translation menu that has an Edit Global Replace Dictionary program.

This program provides a simple interface to allow you to view and edit a Global Replace Dictionary for the current language code.

The Global Replace Dictionary file that is being viewed/edited is shown in the Window title and exists in the Settings folder. The default file is:

settings\Lang_EN_Global_Replace_Dictionary.TXT

The Global Replace Dictionary consists of pairs of Original text and New text. During the translation process the phrase to be translated is checked to see if the Original text is found anywhere within the phrase.

For example if the Original text is 'stock code' and the New text is 'part number' and the phrase to be translated is

The stock code does not exist

then the Original text 'stock code' is found in the phrase and therefore the translated phrase will be

The part number does not exist

The Global Replace Dictionary is particularly useful when making terminology changes within SYSPRO in an English environment rather than any using it for Language Translation.

Note that when defining a Global Replace Dictionary that the Original text must match the exact case of the phrase. For this reason it can be a good idea to define the possible case combinations as shown below:

Original Phrase | New Phrase | Notes
Stock code | Part number | Normal prompts etc
Stock Code | Part Number | Window headings and push buttons
stock code | part number | Embedded within other text

There is a limit of 500 phrase pairs in this Global Replace Dictionary.

Note that when you Save any changes to this Dictionary that the Dictionary is reloaded immediately for your current system. Therefore as you exit to the menu and load another program the newly loaded program will already be using the new Global Replace Dictionary. Other operators will only see these changes when they next Login to SYSPRO.

On a Client/Server system the changes are made to the Server and the new Global Replace Dictionary is immediately self-healed to your specific Client for the changes to take effect immediately.

See also

What's new about SYSPRO 6.0 issue 010, TRANSLATE-TEXT, TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-GET, TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-LIST


Resource Locking

Introduction

Developers occasionally have the requirement that they need to be able to lock a resource that is not a table or row within a table. The resource locking functions provide a simple to use and standardized method of locking abstract resources without the problem of releasing the locks if something goes wrong and the program or computer crashes or the operator terminates the process unexpectedly.

This requirement is more common when developing using some of the later user interface technologies available in SYSPRO 6.1.

A good example is the Inventory Alternate Stock Code Maintenance program. In this case we may wish to lock the parent stock code during the maintenance of it's alternates - however locking the stock code is a serious thing to do in SYSPRO. In reality we just wish to prevent others from maintaining alternate stock codes for the same parent item at the same time.

Using the Resource Locking functions we could use a lock type called 'INVPAL' (the name of the alternate stock code program) and when we enter the stock code (say 'B100') lock the resource:

Company = Current

Lock type = 'INVPAL'

Lock key = 'B100'

In the (unlikely) case that someone else is editing alternate stock codes for the same item at the same time when you try to add this resource lock (RESOURCE-LOCK-ADD) you will receive a lock status and information about who is holding the lock.

A simple mechanism is provided to release the lock when you have finished editing the alternate stock codes for the item.

Another simple example would be when editing a text file (such as an XML file) as you cannot use traditional row or table locks. In this case the resource could be the file being edited.

A test harness has been provided called SDKLCK that demonstrates the Resource Locking functions. In addition this can be used to view, and if required, animate the code.

Overview of the new resource locking functions

When you wish to acquire a resource lock you must initialize the group field named WW-LOCK-FIELDS. Then populate the following fields as applicable:

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

When you initialized WW-LOCK-FIELDS this company field will be set to spaces which indicates the 'current' company id. This has been done as this is by far the most common requirement. However you can move in a specific company required.

Move LOW-VALUES to this company field to indicate that you require a system-wide resource lock.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

This could be the name of the program or any other string that uniquely identifies the resource to be locked.

Note that as the field is 10 characters long you could use a combination of program or file name and a short string.

It is recommended that third party developers prefix their codes with a hyphen ('-') as none of the standard codes used by SYSPRO applications start with a hyphen.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

In the example of the alternate stock code maintenance it would be logical to use the parent stock code being maintained as the key field.

If you have the situation where there is no 'key' then you can just move in the same code as moved to the field WW-LOCK-TYP. This field may not be left blank.

WW-LOCK-DES (mandatory)

This specifies a mandatory 40 character description of the type of resource being locked.

In the example of the alternate stock code maintenance it would be logical to use a description 'Alternate stock codes'.

The resource lock description is useful for administrators viewing the resource lock table. In addition when another user attempts to lock exactly the same company, type, key that you have locked they will see the resource lock description in any message displayed.

Because of these reasons it is highly recommended that you use a friendly description of the resource lock type.

WW-LOCK-FLG (optional)

This specifies an optional 1 character flag that applies to the specific resource being locked.

When another user attempts to lock exactly the same company, type, key that you have locked, the program that they are using can detect this and either display a standard task dialog or the application can retrieve this flag (and any optional reference - see below) and use this for further action or display a custom message. This could be used to further describe the resource being locked.

WW-LOCK-REF (optional)

This specifies an optional 60 character reference that applies to the specific resource being locked.

When another user attempts to lock exactly the same company, type, key that you have locked, the program that they are using can detect this and either display a standard task dialog or the application can retrieve this reference (and any optional flag - see above) and use this for further action or display a custom message. This could be used to further describe the resource being locked.

Once you have setup the above fields (only type, key and description are mandatory) you then perform either the RESOURCE-LOCK-ADD or RESOURCE-LOCK-ADD-MSG functions.

Both of these functions first read for any existing resource locks (the file ADMLCK is used for this purpose) and if the resource is not currently locked then your lock will be added. The key of the resource lock is company, type and key.

However if the resource lock has already been acquired by another user then you can test the logical values STAT-OK and STAT-LCK to determine your program action. If you used the RESOURCE-LOCK-ADD-MSG function then the operator will receive a task dialog similar to the following:

Note that this shows the resource lock description, the operator name and operator code who acquired the lock and the date and time when the lock was acquired (the date is shown using your long date format).

After the operator clicks 'OK' you will receive a STAT-LCK value that can be used to control your program logic.

The following code fragment is taken from the alternate stock code maintenance program (INVPAL):

INITIALIZE WW-LOCK-FIELDS.

MOVE D-COMPID TO WW-LOCK-COM.

MOVE "INVPAL" TO WW-LOCK-TYP.

MOVE D-ENT-STOCK TO WW-LOCK-KEY.

MOVE "Alternate stock code" TO WW-LOCK-DES.

PERFORM RESOURCE-LOCK-ADD-MSG.

IF STAT-LCK

MOVE "L" TO D-VALID-CODE

ELSE

MOVE "Y" TO D-VALID-CODE

END-IF.

When the RESOURCE-LOCK-ADD or RESOURCE-LOCK-ADD-MSG functions return with a STAT-LCK value they also return details about the locked resource. These fields include:

WW-LOCK-DES

The description of the resource lock.

WW-LOCK-OPR

The operator code showing who acquired the lock.

WW-LOCK-NAM

The operator name showing who acquired the lock.

WW-LOCK-DAT

The date that the lock was acquired in CCYYMMDD format.

WW-LOCK-TIM

The time that the lock was acquired in HHMMSSFF format (where FF means 1/100ths of a second).

WW-LOCK-REF

The optional reference against the resource lock.

WW-LOCK-FLG

The optional flag against the resource lock.

Testing a resource lock

If required you can test whether a resource is already locked and either handle this yourself or have the system display a standard task dialog. The functions are RESOURCE-LOCK-TEST and RESOURCE-LOCK-TEST-MSG.

As the functions to add a resource lock also test the lock first it is rare that you require to use these specific 'TEST' functions.

The input parameters to this function are:

WW-LOCK-FIELDS

This group field must be initialized before moving in the following values.

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

If the resource is locked by someone else then this function will return a STAT-LCK logical value and the existing lock is left unchanged.

Deleting a resource lock

Once you have used the RESOURCE-LOCK-ADD or RESOURCE-LOCK-ADD-MSG functions it is best practice to release these locks once you have finished working with the resource.

This is done by performing the RESOURCE-LOCK-DELETE function.

The input parameters to this function are:

WW-LOCK-FIELDS

This group field must be initialized before moving in the following values.

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

If the resource is locked by someone else then this function will return a STAT-LCK logical value and the existing lock is left unchanged.

It is highly recommended that you define a field in working storage that flags whether you have acquired a lock. Then you can ensure that when you program exits (e.g. in the ENDJOB paragraph) or elsewhere that you clear any remaining lock using this function.

How do the resource locking functions work?

There is an ISAM resource lock file called ADMLCK used to store the resource locks.

When you add a resource lock the system adds a record to this file. It also applies a record lock to the record inserted.

When the system tests for an existing lock it reads the record from ADMLCK and if the record exists AND it is locked then the existing information is returned and the STAT-LCK logical value is set. However if the record exists but it is not locked then it is assumed that the instance that had previously locked the record had exited prematurely (when you logout of SYSPRO any record locks are typically released). Therefore the system is self-healing.

The ADMLCK file is a system-wide file stored in the working directory. The key is defined as:

6.1 01 ADMLCK-REC.

03 ADMLCK-KEY.

05 ADMLCK-COM PIC X.

* SQL=LockCompany

* Company id

* Spaces - system-wide

05 ADMLCK-TYP PIC X(10).

* SQL=LockType

* Lock type

* (eg program

* or program and sub-type)

05 ADMLCK-KEY-AREA PIC X(80).

* SQL=KeyField

* Key field being locked

Note that you can either use the standard functions (RESOURCE-LOCK-ADD-MSG or RESOURCE-LOCK-TEST-MSG) to cause a message to be shown if the resource is locked by someone else or you can create your own custom messages using a message box or task dialog.

See also

Deploying custom screensets, message box, task dialog, RESOURCE-LOCK-ADD, RESOURCE-LOCK-ADD-MSG, RESOURCE-LOCK-DELETE, RESOURCE-LOCK-TEST, RESOURCE-LOCK-TEST-MSG


Saving Preferences

Introduction

This article explains how you can easily create operator preferences without having to add any code in your Net Express programs.

Note: This article is aimed at SYSPRO 6.0 issue 009 and later.

The preference file

SYSPRO has a preference file (stored on the client in a client/server system) called BASE\SETTINGS\ADMLST.DAT.

The key to this ISAM file is a 6 character operator code and a 12 character program name. See the code fragment from ADMLST.MAI below:

01 ADMLST-REC.

03 ADMLST-KEY.

05 ADMLST-OPERATOR PIC X(6).

* Operator code

05 ADMLST-PROGRAM PIC X(12).

* Program

This file is generally used by the SYSPRO system to store and retrieve the listview settings including the column widths, ordering, color etc.

The key is the operator code followed by the name of the listview. For example if you are logged in as ADMIN the preference for the Stock code browse listview (IMPBSTLV) is stored against the key:

'ADMIN IMPBSTLV '

Storing and retrieving your own preferences

SYSPRO allows you to store your own preferences using the ADMLST.DAT file. You can store up to 255 characters of preferences against an operator by passing a unique code in place of the listview name shown above.

To avoid conflict with any standard SYSPRO preferences you should start your unique code with an underscore ('_') and make it a total of 6 characters in length (including the underscore).

Useful hint

To allow you to store many preferences using the same code you can use the concept of a table with one occurrence to concatenate multiple preferences into a single string. You can save up to 255 characters against a single code using this technique.

Suppose you have the following three preferences defined in your data block:

PREF-TABLE 1

PREF-A X 1.0

PREF-B 9 1.0

PREF-C X 2.0

You can save and read back these preferences using the following dialog functions by storing them against the unique code '_MYPRF'.

*

SAVE-PREF-PROC

MOVE "SAVE" S-FR-MSG

MOVE "_MYPRF" S-FR-PAR

MOVE PREF-TABLE S-FR-EXT

CALLOUT "IMPACTW1" 3 $NULL

MOVE " " S-FR-PAR

*

READ-PREF-PROC

MOVE "READ" S-FR-MSG

MOVE "_MYPRF" S-FR-PAR

CALLOUT "IMPACTW1" 3 $NULL

MOVE " " S-FR-PAR

MOVE S-FR-EXT PREF-TABLE

Assuming the operator code is 'ADMIN' and the screenset is 'IMPBST' the key used to store these preferences will be:

'ADMIN IMPBST_MYPRF'

Note: the operator code is determined from the standard data block field S-OPER and the first 6 characters from the standard data block field S-SCREENSET is used for the program name.

See also

Dialog Functions by name, Dialog Functions by Type


SYSPRO Diagnostics

SYSPRO and e.net solutions have various diagnostic routines that are available to help identify and resolve problems that may occur.

Intended use

These diagnostic features are solely intended to help identify and resolve problems that may be occurring and should only be enabled for the minimum time required to find the problem. Some of the routines create output logs that may slow the system and use excessive disk space. Generally these should be used in a development environment.

Configuring Diagnostics

To configure SYSPRO diagnostics you should use the SYSPRO System Setup program and select one of the choices against the 'Diagnostics:' prompt as shown below. As soon as the setting has been saved the diagnostic option will be enabled. The remainder of this topic covers the various options available.

Diagnostic options available

The options available from the 'Diagnostic' pull down are only a sample of the possible options. In addition you may enter any 6 character value at the Diagnostic prompt. Note that the diagnostic options are case-sensitive.

The diagnostic options are explained below. These are subject to change.

Diagnostic option - sql01

The 'sql01' option causes various programs that have been optimized for SQL to output a trace of the SQL statement being issued. This includes the SQL statements issued by the Report Writer in an SQL environment.

The file that is generated is base\settings\{oper}.SQL - where {oper} is the operator code. For example the ADMIN operator would have a file called: base\settings\ADMIN.SQL

The 'sql01' option will only contain the last SQL statement that was issued.

Note that this diagnostic is available from SYSPRO 6.0 issue 007 onwards.

Diagnostic option - sql02

The 'sql02' option causes various programs that have been optimized for SQL to output a trace of the SQL statement being issued. This includes the SQL statements issued by the Report Writer in an SQL environment.

The file that is generated is base\settings\{oper}.SQL - where {oper} is the operator code. For example the ADMIN operator would have a file called: base\settings\ADMIN.SQL

The 'sql02' option will accumulate all SQL statements to the log file. Warning - this file may grow rapidly.

Note that this diagnostic is available from SYSPRO 6.0 issue 007 onwards.

Diagnostic option - sys01

The 'sys01' option allows developers and support personnel to view the names of each file that is being transferred to/from a client in a client/server environment.

This diagnostic option outputs an entry to a log file before and after each file transfer. The information contains the date and time, target system (client or server), transfer type (binary or ASCII), status (only relevant for the 'After copy' information) and the file names (client and server).

The file that is generated is base\settings\{oper}.TXT - where {oper} is the operator code. For example the ADMIN operator would have a file called: base\settings\ADMIN.TXT

The 'sys01' option will accumulate all file transfers to/from a server for all operators to the log file. Warning - this file may grow rapidly.

There are similar diagnostics that just display a message box rather than output to a log file (see 'sys02' and 'sys03')

Note that this diagnostic is available from SYSPRO 6.0 issue 010 SP2 onwards.

Diagnostic option - sys02

The 'sys02' option allows developers and support personnel to view the names of each file that is being transferred to/from a client in a client/server environment.

This diagnostic option displays a message box before and after each file transfer. The information contains the target system (client or server), transfer type (binary or ASCII), status (only relevant for the 'After copy' information) and the file names (client and server).

Warning - there may be many message boxes invoked so only set this option when no-one else is using the system. Also note that it is possible that the message box program itself may not be available on the client system - in this case this diagnostic may cause a CCI error and crash the client/server process. If this happens then switch off the 'sys02' diagnostics (remove the IMPCOM= entry from your IMPACT.INI file).

There are similar diagnostics (see 'sys01' and 'sys03').

Note that this diagnostic is available from SYSPRO 6.0 issue 010 SP2 onwards.

Diagnostic option - sys03

The 'sys03' option allows developers and support personnel to view the names of each file that is being transferred to/from a client in a client/server environment.

This diagnostic option displays a message box after each file transfer. The information contains the target system (client or server), transfer type (binary or ASCII), status and the file names (client and server).

Note that this diagnostic is very similar to 'sys02' except that only a single message box is shown per transfer whereas 'sys02' shows a before and after message box.

Warning - there may be many message boxes invoked so only set this option when no-one else is using the system. Also note that it is possible that the message box program itself may not be available on the client system - in this case this diagnostic may cause a CCI error and crash the client/server process. If this happens then switch off the 'sys02' diagnostics (remove the IMPCOM= entry from your IMPACT.INI file).

There are similar diagnostics (see 'sys01' and 'sys02').

Note that this diagnostic is available from SYSPRO 6.0 issue 010 SP2 onwards.

Diagnostic option - enet01

The 'enet01' option causes the e.net Encore.dll to output a log of each business object that has been run together with the status. A non-zero status indicates an exception was raised.

The file that is generated is base\settings\enetlog.txt

Warning - this file may grow rapidly.

See the topic e.net Diagnostics for more detail.

Note that this diagnostic is available from SYSPRO 6.0 issue 007 onwards.

Diagnostic option - enet02

The 'enet02' option causes the e.net Document Flow Manager to output a log of each business object that has been run.

The file that is generated is base\settings\enetlog02.txt

Warning - this file may grow rapidly.

See the topic Document Flow Manager Diagnostics for more detail.

Note that this diagnostic is available from SYSPRO 6.0 issue 007 onwards.

Diagnostic option - enet03

The 'enet03' option causes each program (business object or sub program) that is run in a COM environment to verify that it has been compiled with the correct directives. Once the 'enet03' diagnostic option has been selected (and any internet services restarted) an exception will be raised indicating any business object that was compiled with incorrect directives.

This diagnostic is primarily designed to identify hanging processes running in an ASP 3.0 environment.

See the topic Developing for a COM Environment for more detail.

Note that this diagnostic is available from SYSPRO 6.0 issue 008 onwards.

Also note that this diagnostic has been removed from SYSPRO 6.1 onwards as all programs have been developed with the appropriate directives - See What's new about SYSPRO 6.1.

Removing the diagnostics

It is possible that the diagnostics could cause you system to work incorrectly or so you cannot log in. If this is the case then locate your IMPACT.INI and remove the line that starts:

IMPCOM=

When you next log in the diagnostics will be reset and disabled.

See also

e.net Diagnostics, Document Flow Manager Diagnostics, SQL Server tuning code, Developing for a COM Environment, What's new about SYSPRO 6.1


Unit Quantity Feature

Introduction

One of the new features of Encore 5.1 is that the Distribution modules have been enhanced to allow specified stock items to request and display the quantities using two parameters (such as Cases and Pieces) rather that the normal Units and Decimals. This facility has been called the Unit Quantity feature.

The implementation involves using a set of standard routines when displaying or calculating quantities for this type of stock item. The routines are defined in the copybooks PROEXT.PRO and EXT.WRK. All working storage fields and routines are prefixed with UNITQ-

The stock items affected are identified by a new Inventory master field called INVMST-UNITS-ONLY, seen on the General Tab in the Stock Code Maintenance program.

The following explanations demonstrate use of the various functions and when they should be used.

Converting quantities from units/decimals to cases/pieces

Use the function UNITQ-DECIMALS-TO-CASES

MOVE QUANTITY TO UNITQ-QTY

MOVE INVMST-FACT TO UNITQ-FACTOR

PERFORM UNITQ-DECIMALS-TO-CASES

MOVE UNITQ-CASES TO QTY-CASES

MOVE UNITQ-PIECES TO QTY-PIECES

Initial value:

QUANTITY = 10.5 (assume 6 units in a packet)

Result:

QTY-CASES = 10

QTY-PIECES = 3

Converting from cases/pieces to units/decimals

Use the function UNITQ-CASES-TO-DECIMALS

MOVE QTY-CASES TO UNITQ-CASES

MOVE QTY-PIECES TO UNITQ-PIECES

MOVE INVMST-FACT TO UNITQ-FACTOR

PERFORM UNITQ-CASES-TO-DECIMALS

MOVE UNITQ-QTY TO QUANTITY

Initial values:

QTY-CASES = 10 (assume 6 units in a packet)

QTY-PIECES = 2

Result:

QUANTITY = 10,333

Displaying quantities in a listview

Use the function UNITQ-EDIT-CASES-L

If quantity is in units and decimals:

MOVE "D" TO UNITQ-QTY-FORMAT

MOVE QUANTITY TO UNITQ-QTY

MOVE INVMST-FACT TO UNITQ-FACTOR

MOVE INVMST-UNIT-DEC TO UNITQ-UNIT-DEC

PERFORM UNITQ-EDIT-CASES-L

MOVE UNITQ-EDITED-QTY TO QUANTITY-ALPHA

Initial value:

QUANTITY = 10.5- (assume 12 bottles in a case)

Result:

QUANTITY-ALPHA = -10/06

(In this example, quantity is first converted to cases and pieces and then formatted)

If quantity is in cases and pieces:

MOVE SPACES TO UNITQ-QTY-FORMAT

MOVE CASES-QTY TO UNITQ-CASES

MOVE PIECES-QTY TO UNITQ-PIECES

MOVE INVMST-UNIT-DEC TO UNITQ-UNIT-DEC

PERFORM UNITQ-EDIT-CASES-L

MOVE UNITQ-EDITED-QTY TO QUANTITY-ALPHA

Initial values:

CASES-QTY = 10- (assume 12 bottles in a case)

PIECES-QTY = 06

Result:

QUANTITY-ALPHA = -10/06

Displaying or Printing the Quantity

Use the function UNITQ-EDIT-CASES-D

If quantity is in units and decimals:

MOVE "D" TO UNITQ-QTY-FORMAT

MOVE QUANTITY TO UNITQ-QTY

MOVE INVMST-FACT TO UNITQ-FACTOR

MOVE INVMST-UNIT-DEC TO UNITQ-UNIT-DEC

PERFORM UNITQ-EDIT-CASES-D

MOVE UNITQ-EDITED-QTY TO QUANTITY-ALPHA

Initial value:

QUANTITY = 10.5- (assume 12 bottles in a case)

result:

QUANTITY-ALPHA = 10/06-

(In this example, quantity is first converted to cases and pieces and then formatted)

If quantity is in cases and pieces:

MOVE SPACES TO UNITQ-QTY-FORMAT

MOVE CASES-QTY TO UNITQ-CASES

MOVE PIECES-QTY TO UNITQ-PIECES

MOVE INVMST-UNIT-DEC TO UNITQ-UNIT-DEC

PERFORM UNITQ-EDIT-CASES-D

MOVE UNITQ-EDITED-QTY TO QUANTITY-ALPHA

Initial values:

CASES-QTY = 10- (assume 12 bottles in a case)

PIECES-QTY = 06

Result:

QUANTITY-ALPHA = -10/06

Calculating a Quantity

When adding or subtracting quantities for UNITS-ONLY stock items, it is important to do the calculations in cases and pieces so that no quantity is lost due to rounding problems. For this purpose, use the function UNITQ-CALC-UNITS.

However, you can only add up to 5 quantities together, or subtract 4 quantities from another quantity, on a single call of that routine. If the calculation involves addition and subtraction in the same COMPUTE statement, these have to be done separately. See the following examples:

If quantities are in units and decimals:

IF INVMST-UNITS-ONLY = "Y"

MOVE ZEROS TO UNITQ-QTYS-TABLE

MOVE TOTAL-QUANTITY TO UNITQ-CALC-QTY(1)

MOVE QUANTITY-1 TO UNITQ-CALC-QTY(2)

MOVE QUANTITY-2 TO UNITQ-CALC-QTY(3)

MOVE "A" TO UNITQ-OPERATION

MOVE INVMST-FACT TO UNITQ-FACTOR

PERFORM UNITQ-CALC-QTYS

MOVE UNITQ-QTY TO TOTAL-QUANTITY

ELSE

COMPUTE TOTAL-QUANTITY = TOTAL-QUANTITY + QUANTITY-1 + QUANTITY-2

IF INVMST-UNITS-ONLY = "Y"

MOVE ZEROS TO UNITQ-QTYS-TABLE

MOVE REMAIN-QUANTITY TO UNITQ-CALC-QTY(1)

MOVE QUANTITY-1 TO UNITQ-CALC-QTY(2)

MOVE QUANTITY-2 TO UNITQ-CALC-QTY(3)

MOVE "S" TO UNITQ-OPERATION

MOVE INVMST-FACT TO UNITQ-FACTOR

PERFORM UNITQ-CALC-QTYS

MOVE UNITQ-CASES TO REMAIN-QUANTITY

ELSE

COMPUTE REMAIN-QUANTITY = REMAIN-QUANTITY - QUANTITY-1 - QUANTITY-2.

If quantities are in cases and pieces:

IF INVMST-UNITS-ONLY = "Y"

MOVE ZEROS TO UNITQ-QTYS-TABLE

MOVE TOTAL-CASES TO UNITQ-CALC-CASES(1)

MOVE TOTAL-PIECES TO UNITQ-CALC-PIECES(1)

MOVE CASES-QTY-1 TO UNITQ-CALC-CASES(2)

MOVE PIECES-QTY-1 TO UNITQ-CALC-PIECES(2)

MOVE CASES-QTY-2 TO UNITQ-CALC-CASES(3)

MOVE PIECES-QTY-2 TO UNITQ-CALC-PIECES(3)

MOVE "A" TO UNITQ-OPERATION

MOVE INVMST-FACT TO UNITQ-FACTOR

PERFORM UNITQ-CALC-QTYS

MOVE UNITQ-CASES TO TOTAL-CASES

MOVE UNITQ-PIECES TO TOTAL-PIECES

ELSE

COMPUTE TOTAL-QUANTITY = TOTAL-QUANTITY + QUANTITY-1 + QUANTITY-2

IF INVMST-UNITS-ONLY = "Y"

MOVE ZEROS TO UNITQ-QTYS-TABLE

MOVE REMAIN-CASES TO UNITQ-CALC-CASES(1)

MOVE REMAIN-PIECES TO UNITQ-CALC-PIECES(1)

MOVE CASES-QTY-1 TO UNITQ-CALC-CASES(2)

MOVE PIECES-QTY-1 TO UNITQ-CALC-PIECES(2)

MOVE CASES-QTY-2 TO UNITQ-CALC-CASES(3)

MOVE PIECES-QTY-2 TO UNITQ-CALC-PIECES(3)

MOVE "S" TO UNITQ-OPERATION

MOVE INVMST-FACT TO UNITQ-FACTOR

PERFORM UNITQ-CALC-QTYS

MOVE UNITQ-CASES TO REMAIN-CASES

MOVE UNITQ-PIECES TO REMAIN-PIECES

ELSE

COMPUTE REMAIN-QUANTITY = REMAIN-QUANTITY - QUANTITY-1 - QUANTITY-2.

The function UNITQ-CALC-QTYS always returns the fields UNITQ-QTY, UNITQ-CASES and UNITQ-PIECES, so that you have the result in both formats.

All the fields required for the use of UNITQ routines are documented in the copybook PROEXT.PRO.

See also


Using GUIDs

Introduction

This article introduces the topic of GUIDs and some of the reasons why they are used. It also covers some of the functions available for generating, storing and converting GUIDs and discusses some of the best practices when working with GUIDs.

What is a GUID?

A GUID is a Globally Unique ID. This is a 128 bit (16 character) field that is guaranteed to be unique.

As the 16 byte format of a GUID can contain virtually any binary values there is an industry standard 38 byte format that is often used to display GUIDs. For example you will often see 38 character format GUIDs in the Windows registry.

For simplicity we will refer to these as GUID16 and GUID38 format GUIDs. Note that they both can represent the same GUID but one is visible and one is often not. See the following example GUID shown using the GUID38 format:

{5e845202-8723-4828-84ff-088d0bd43864}

The advantages of using a GUID is that (generally speaking) generating a GUID on one computer at a specific moment in time is virtually guaranteed to generate a different GUID to any other previously generated GUID. This can be useful when storing a GUID as a key field.

Contact Management and use of a ContactId

There is a new Contact Management System (CMS) included in Issue 010 SP1. This is developed using many of the new controls, however it is still a traditional SYSPRO application and therefore works in a client/server environment and with ISAM or SQL data storage.

One of the techniques used for the first time in CMS is that the key to the Contact master table (CRMCON / CrmContact) is a GUID.

Within your Net Express programs this is stored and used as a X(16) field. Also in a record layout it is stored as X(16). However in the data dictionary it is defined as a 'uniqueidentifier' column (the field is defined as Alphanumeric but also the field DDSFLD-GUID is a 'G').

In addition in a SQL Server environment the ContactId column has a data type of 'uniqueidentifier'.

The data dictionary has been enhanced to cater for GUIDs.

Working with GUIDs

It is highly recommended that a GUID of any format is never displayed or printed as it's a meaningless string to an operator. However some programs, such as generic utilities, may need to display the contents of a column such as the ContactId column in the CrmContact table.

To assist with this there are two functions for converting a GUID16 to GUID38 format and vice versa. The functions are:

CONVERT-GUID16-TO-GUID38

CONVERT-GUID38-TO-GUID16

Converting a ContactId to a Contact Name

When using the Contact Management System you may have read or been passed a ContactId. Whilst you can obviously read the CrmContact master file for Contact information you may often just want to display the Contact Name.

There is a specific function for retrieving the Contact Name give the ContactId (GUID). The function CMS-READ-CONTACT-NAME-FRM-GUID is to be used for this purpose.

The reverse is also available allowing you to retrieve a ContactId passing a Contact Name. The function is called CMS-READ-CONTACT-GUID-FRM-NAME. Note that if there are multiple Contacts with the same name then only one ContactId will be returned.

Using GUIDs with Generic Functions

The generic functions such as Notepad, Multimedia and Custom Forms must not use a GUID16 format GUID as the generic key - in this case the GUID38 format should be used.

Warning about using GUID16 format data

It's important to realize that a GUID16 format GUID can contain virtually any Binary value and care must be taken when storing this information (for example in a text file) or passing information between systems.

For example if you wish to store a GUID, such as a ContactId, in a listview column you must use the GUID38 format to avoid spurious problems populating or using the Listview.

Generating GUIDs

There is a function called GENERATE-GUID that should be used to generate a GUID. For convenience this function returns the GUID in both GUID16 and GUID38 format.

See also

CMS-READ-CONTACT-GUID-FRM-NAME, CMS-READ-CONTACT-NAME-FRM-GUID, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16, GENERATE-GUID


Dialog functions by name

This is a list of the standard functions available from a screenset using the standard SYSPRO copybooks.

How to use the built-in functions

Each function works in a similar style. Generally you must move the name of the function to a standard data block field called S-FR-MSG. Then optionally move parameters to other standard data block fields (such as S-FR-PAR and S-FR-EXT) then you must use a RETC to inform the SYSPRO program to run the desired function.

Some of the functions return parameters or a status code back into the standard data block.

S-ABOUT | Call the About SYSPRO dialog
S-ALT | Call the System manager and Favorites menu
S-B-XXXXXX | Call a SYSPRO browse
S-CALL | Call a SYSPRO program
S-CALLNC | Call a SYSPRO program but do not cancel it from memory
S-CANCEL | Cancels a program called with the S-CALLNC function
S-CLPCOPY | Copy the selected contents of an entry field to the clipboard
S-CLPCUT | Cut the selected contents of an entry field to the clipboard
S-CLPDEL | Delete selected text from an entry field
S-CLPPASTE | Paste the clipboard to an entry field
S-CLPSEL | Select entire text of an entry field
S-DATE | Call the browse on dates program
S-DATECOMP | Compare two 6 digit dates
S-EXIT | Exit current program
S-EXITENC | Exit SYSPRO entirely
S-EXITRUN | Exit current program and run another
S-F2 | Shift+F2 function – Quick find
S-F3 | Shift+F3 function – not currently used
S-F4 | Shift+F4 function – toggle print preview on/off
S-F5 | Shift+F5 function – Page setup dialog
S-F6 | Shift+F6 function – Print setup dialog
S-F7 | Shift+F7 function – System Information
S-F8 | Shift+F8 function – Save/Restore printer information for program
S-FILE-BRW | Browse on files
S-FORM-DEL | Delete a custom form for a key field
S-FORM-EDT | Edit a custom form for a key field
S-FORM-GET | Get the single form field value for a custom form
S-FORM-TST | Test a custom form for mandatory fields
S-HELP | Call the on-line help system
S-LOWER | Convert string to lowercase
S-MDEL | Delete multimedia objects for a key field
S-MEDIT | Edit/define multimedia objects for a key field
S-MPATH | Retrieves the path to a multimedia object
S-MPLAY | View/play multimedia objects for a key field
S-NCOPY | Copy notes for an item to another item
S-NDEL | Delete generic notes for a key field
S-NEDIT | View and edit generic notepad
S-NGRTF | Retrieve RTF filename
S-NMOVE | Move notes from one item to another
S-NTEST | Test if generic notes exist for a key field
S-NVIEW | View (not edit) generic notes
S-OSAFER | Transfer a file from server to client (ASCII mode)
S-OSAFERS | Transfer a file from client to server (ASCII mode)
S-OSCMD | Execute an operating system command (on client if client/server)
S-OSCMDS | Execute an operating system command (on sever if client/server)
S-OSCOPYS | Copy one file to another (on server if client/server)
S-OSDEL | Delete a file (on client if client/server)
S-OSDELS | Delete a file (on server if client/server)
S-OSGETD | Retrieve the current directory (on client if client/server)
S-OSGETDS | Retrieve the current directory (on server if client/server)
S-OSMKDR | Create directory on the client
S-OSMKDRS | Create directory on the server
S-OSSETD | Set the current directory (on client if client/server)
S-OSSETDS | Set the current directory (on server if client/server)
S-OSXFER | Transfer a file from the server to a client (client/server only)
S-OSXFERS | Transfer a file from the server to the client (client/server only)
S-PASSASK | Ask password and verify against an existing password
S-PASSINFO | Test whether a password exists for the key field
S-PASSCTL | Define a password control for the password type
S-PASSINFO | Test whether a password exists for the key field
S-PASSSETN | Set a new password – screenset must have asked new password
S-PASSVER | Verify a password requested in your application
S-UPLOWER | Convert string to initial capital rest in lowercase
S-UPPER | Convert string to uppercase


Dialog functions by type

This is a list of the standard functions available from a screenset using the standard SYSPRO copybooks.

How to use the built-in functions

Each function works in a similar style. Generally you must move the name of the function to a standard data block field called S-FR-MSG. Then optionally move parameters to other standard data block fields (such as S-FR-PAR and S-FR-EXT) then you must use a RETC to inform the SYSPRO program to run the desired function.

Some of the functions return parameters or a status code back into the standard data block.

Converting case

S-LOWER | Convert string to lowercase
S-UPLOWER | Convert string to initial capital rest in lowercase
S-UPPER | Convert string to uppercase

Date handling

S-DATE | Call the browse on dates program
S-DATECOMP | Compare two 6 digit dates

Calling and exiting programs

S-ABOUT | Call the About SYSPRO dialog
S-B-XXXXXX | Call a SYSPRO browse
S-CALL | Call a SYSPRO program
S-CALLNC | Call a SYSPRO program but do not cancel it from memory
S-CANCEL | Cancels a program called with the S-CALLNC function
S-DATE | Call the browse on dates program
S-EXIT | Exit current program
S-EXITENC | Exit SYSPRO entirely
S-EXITRUN | Exit current program and run another
S-FILE-BRW | Browse on files

Calling operating system commands, get and set directories and copying files

S-OSAFER | Transfer a file from server to client (ASCII mode)
S-OSAFERS | Transfer a file from client to server (ASCII mode)
S-OSCMD | Execute an operating system command (on client if client/server)
S-OSCMDS | Execute an operating system command (on sever if client/server)
S-OSCOPYS | Copy one file to another (on server if client/server)
S-OSDEL | Delete a file (on client if client/server)
S-OSDELS | Delete a file (on server if client/server)
S-OSGETD | Retrieve the current directory (on client if client/server)
S-OSGETDS | Retrieve the current directory (on server if client/server)
S-OSMKDR | Create directory on client
S-OSMKDRS | Create directory on server
S-OSSETD | Set the current directory (on client if client/server)
S-OSSETDS | Set the current directory (on server if client/server)
S-OSXFER | Transfer a file from the server to a client (client/server only)
S-OSXFERS | Transfer a file from the client to the server (client/server only)

Passwords

S-PASSASK | Ask password and verify against an existing password
S-PASSINFO | Test whether a password exists for the key field
S-PASSCTL | Define a password control for the password type
S-PASSINFO | Test whether a password exists for the key field
S-PASSSETN | Set a new password – screenset must have asked new password
S-PASSVER | Verify a password requested in your application

Clipboard support

S-CLPCOPY | Copy the selected contents of an entry field to the clipboard
S-CLPCUT | Cut the selected contents of an entry field to the clipboard
S-CLPDEL | Delete selected text from an entry field
S-CLPPASTE | Paste the clipboard to an entry field
S-CLPSEL | Select entire text of an entry field

Generic notepad

S-NCOPY | Copy generic notes from one field to another
S-NDEL | Delete generic notes for a key field
S-NEDIT | View and edit generic notepad
S-NGRTF | Retrieve RTF filename
S-NMOVE | Move generic notes from key field to another
S-NTEST | Test if generic notes exist for a key field
S-NVIEW | View generic notes (does not allow editing)

Multimedia

S-MDEL | Delete multimedia objects for a key field
S-MEDIT | Edit/define multimedia objects for a key field
S-MPATH | Retrieves the path to a multimedia object
S-MPLAY | View/play multimedia objects for a key field

Custom forms

S-FORM-DEL | Delete a custom form for a key field
S-FORM-EDT | Edit a custom form for a key field
S-FORM-GET | Get the single form field value for a custom form
S-FORM-TST | Test custom form for mandatory fields

Standard function key functions

S-ALT | F8 - Call the System manager and Favorites menu
S-F2 | Shift+F2 function - Quick find
S-F3 | Shift+F3 function - not currently used
S-F4 | Shift+F4 function - toggle print preview on/off
S-F5 | Shift+F5 function - Page setup dialog
S-F6 | Shift+F6 function - Print setup dialog
S-F7 | Shift+F7 function - System Information
S-F8 | Shift+F8 function - Save/Restore printer information for program
S-HELP | F1 - Call the on-line help system


S-ABOUT

The S-ABOUT function is used to call the About SYSPRO dialog.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

This function is used to call the About SYSPRO dialog.

Sample code

* Call the About SYSPRO Dialog

MOVE "S-ABOUT" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-ALT

The S-ALT function shows the system manager and Favorites menu. This is the same as pressing F8.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The S-ALT calls the program IMPALT which shows the system manager and the Favorites menu.

Sample code

* Handle the F8 function

F8

MOVE "S-ALT" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-B-XXXXXX

The S-B-XXXXXX function is used to call a SYSPRO browse. You replace the XXXXXX characters with the name of the browse program to be called.

You can pass the initial start key for the browse and receive the selected item. Upon completion the function will return back to the next dialog function.

To call other types of programs – such as a Query – use S-CALL.

Input parameters

S-BRW1

This field is initial the primary key to be used. For example when browsing on Stock codes this is the stock code.

S-BRW2

An optional initial key where a browse requires more than one key part. For example when browsing on the list of Customer invoices the field S-BRW1 contains the customer and this field contains the initial invoice. Some browses vary as to how the parameters are passed.

S-BRW3

An optional third parameter

S-BRW4

An optional fourth parameter

S-BRW1-N

If the key being browsed is numeric (such as a journal number) then use this field rather than S-BRW1.

S-BRW2-N

This is used when a second numeric parameter is required.

Output parameters

S-BRW1

This is the returned key of the item selected. Generally if the operator cancelled from the browse this will have the initial value passed.

Remarks

It is extremely easy to call a SYSPRO browse program using this function.

To find out a list of the browses available:

  1. Load SYSPRO

  2. Use File, Run

  3. Click on the browse (or press F9)

  4. Select Browses only

  5. Use the program name shown

Note that most of the browses are under System Admin & Shared Programs

Common browses include:

  • IMPBST Stock code

  • IMPBCS Customer

  • IMPBSP Supplier

  • IMPBSO Sales orders

  • IMPBPO Purchase orders

  • IMPBJB Jobs

Note that when a browse requires two or more parameters the sequence of the parameters required can vary. If you have a problem getting a browse to accept your parameters contact your regional Syspro offices who can assist with the parameters.

Sample code

* Call the Inventory browse (IMPBST) and return selected item

MOVE "S-B-IMPBST" S-FR-MSG

MOVE D-STOCK-CODE S-BRW1

RETC

MOVE S-BRW1 D-STOCK-CODE

SET-FOCUS EF-STOCK-CODE

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-CALL

The S-CALL function is used to call a SYSPRO program. You can pass and receive parameters. Upon completion the function will return back to the next dialog function.

To call a browse and return parameters see S-B-XXXXXX.

Input parameters

S-FR-PAR

The name of the SYSPRO program to be called.

S-FR-EXT

An optional parameter to be passed to LINK-EXTRA.

Output parameters

S-TO-PAR

An optional returned parameter from the program passed via LINK-EXTRA.

Remarks

It is extremely easy to call SYSPRO programs using this function. This can be useful to call queries, reports or just about any other SYSPRO program.

Many of the SYSPRO Query programs accept a parameter and will use this as the initial item to be shown.

Note that not all programs accept parameters.

To call a browse and return parameters you should use S-B-XXXXXX as this allows more parameters to be passed.

Note that in some special circumstances you may need to call a program and not cancel it from memory immediately. In this case you should use S-CALLNC.

Sample code

* Call the Inventory Query program (INVPEN)

MOVE "S-CALL" S-FR-MSG

MOVE "INVPEN" S-FR-PAR

RETC

*

* Call the Inventory Query passing an initial stock code

MOVE "S-CALL" S-FR-MSG

MOVE "INVPEN" S-FR-PAR

MOVE "B100 " S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-B-XXXXXX, S-CALLNC


S-CALLNC

The S-CALLNC function is used to call a SYSPRO program without cancelling it from memory after it has been called. You can pass and receive parameters. Upon completion the function will return back to the next dialog function.

Typically you will use the S-CANCEL function to cancel the program from memory when you have finished.

Input parameters

S-FR-PAR

The name of the SYSPRO program to be called.

S-FR-EXT

An optional parameter to be passed to LINK-EXTRA.

Output parameters

S-TO-PAR

An optional returned parameter from the program passed via LINK-EXTRA.

Remarks

Note that generally when you call programs you should use the S-CALL function. This is identical to the S-CALLNC function except that it automatically cancels the program from memory when it has finished.

Some SYSPRO programs can be called 'with no cancel'. This means that they are invoked the first time and initialize any working fields and open any files required. On subsequent calls they will have the files open and working fields already setup.

These programs remain in memory (using system resources) until they are cancelled from memory using the S-CANCEL function or the operator exits from SYSPRO.

This is equivalent to the functions CALL-PROGRAM-NO-CANCEL and CANCEL-PROGRAM.

Note that to call a browse and return parameters you should use S-B-XXXXXX as this allows more parameters to be passed.

Sample code

* Call a dummy program (DUMMY1)

MOVE "S-CALLNC" S-FR-MSG

MOVE "DUMMY1" S-FR-PAR

RETC

*

* Cancel the program from memory

MOVE "S-CANCEL" S-FR-MSG

MOVE "DUMMY1" S-FR-PAR

RETC

Requirements

Version: Included in SYSPRO 6.0 issue 008 and later.

Copybooks: standard

See also

S-CANCEL, S-CALL, S-B-XXXXXX, CALL-PROGRAM-NO-CANCEL, CANCEL-PROGRAM


S-CANCEL

The S-CANCEL function is used to cancel a SYSPRO program from memory that has previously been called using the S-CALLNC function. Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

The name of the SYSPRO program to be cancelled from memory.

Output parameters

none

Remarks

This function is used to cancel a program from memory that was previously called using the S-CALLNC function.

Some SYSPRO programs can be called 'with no cancel'. This means that they are invoked the first time and initialize any working fields and open any files required. On subsequent calls they will have the files open and working fields already setup.

These programs remain in memory (using system resources) until they are cancelled from memory using the S-CANCEL function or the operator exits from SYSPRO.

Sample code

* Call a dummy program (DUMMY1)

MOVE "S-CALLNC" S-FR-MSG

MOVE "DUMMY1" S-FR-PAR

RETC

*

* Cancel the program from memory

MOVE "S-CANCEL" S-FR-MSG

MOVE "DUMMY1" S-FR-PAR

RETC

Requirements

Version: Included in SYSPRO 6.0 issue 008 and later.

Copybooks: standard

See also

S-CALLNC


S-CLPCOPY

The S-CLPCOPY function is used to copy selected text from an entry field and place it on the windows clipboard. This can subsequently be pasted into another entry field or used by a third party application.

The client windows clipboard (client PC in a client/server system) is always used.

Upon completion the function will return back to the next dialog function.

This is part of the cut, copy, paste, select all and delete functionality.

Input parameters

S-WINHAN

You must move the object handle of the entry field to be used.

Output parameters

none

Remarks

This forms part of the clipboard group of functions consisting of Cut, Copy and Paste. In addition there are Select All and Delete functions to allow text in an entry field to be manipulated.

Note that both entry fields and multi-line entry fields may be referenced.

Sample code

* Copy the selected contents of an entry field to the clipboard

MOVE "S-CLPCOPY" S-FR-MSG

MOVE-OBJECT-HANDLE EF-ENTRY-FIELD S-WINHAN

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CLPCUT, S-CLPPASTE, S-CLPSEL, S-CLPDEL


S-CLPCUT

The S-CLPCUT function is used to cut selected text from an entry field and place it on the windows clipboard. This can subsequently be pasted into another entry field or used by a third party application.

The client windows clipboard (client PC in a client/server system) is always used.

Upon completion the function will return back to the next dialog function.

This is part of the cut, copy, paste, select all and delete functionality.

Input parameters

S-WINHAN

You must move the object handle of the entry field to be used.

Output parameters

none

Remarks

This forms part of the clipboard group of functions consisting of Cut, Copy and Paste. In addition there are Select All and Delete functions to allow text in an entry field to be manipulated.

Note that both entry fields and multi-line entry fields may be referenced.

Sample code

* Cut the selected contents of an entry field to the clipboard

MOVE "S-CLPCUT" S-FR-MSG

MOVE-OBJECT-HANDLE EF-ENTRY-FIELD S-WINHAN

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CLPCOPY, S-CLPPASTE, S-CLPSEL, S-CLPDEL


S-CLPDEL

The S-CLPDEL function is used to delete selected text in an entry field.

Upon completion the function will return back to the next dialog function.

This is part of the cut, copy, paste, select all and delete functionality.

Input parameters

S-WINHAN

You must move the object handle of the entry field to be used.

Output parameters

none

Remarks

This forms part of the clipboard group of functions consisting of Cut, Copy and Paste. In addition there are Select All and Delete functions to allow text in an entry field to be manipulated.

Note that both entry fields and multi-line entry fields may be referenced.

Sample code

* Delete selected text from an entry field

MOVE "S-CLPDEL" S-FR-MSG

MOVE-OBJECT-HANDLE EF-ENTRY-FIELD S-WINHAN

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CLPCUT, S-CLPCOPY, S-CLPPASTE, S-CLPSEL


S-CLPPASTE

The S-CLPPASTE function is used to paste the current text contents of the clipboard into an entry field.

The client windows clipboard (client PC in a client/server system) is always used.

Upon completion the function will return back to the next dialog function.

This is part of the cut, copy, paste, select all and delete functionality.

Input parameters

S-WINHAN

You must move the object handle of the entry field to be used.

Output parameters

none

Remarks

This forms part of the clipboard group of functions consisting of Cut, Copy and Paste. In addition there are Select All and Delete functions to allow text in an entry field to be manipulated.

Note that both entry fields and multi-line entry fields may be referenced.

Sample code

* Paste the contents of the clipboard to an entry field

MOVE "S-CLPPASTE" S-FR-MSG

MOVE-OBJECT-HANDLE EF-ENTRY-FIELD S-WINHAN

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CLPCUT, S-CLPCOPY, S-CLPSEL, S-CLPDEL


S-CLPSEL

The S-CLPSEL function is used to select the entire contents of an entry field. This can be used prior to cutting or copying it to the clipboard.

Upon completion the function will return back to the next dialog function.

This is part of the cut, copy, paste, select all and delete functionality.

Input parameters

S-WINHAN

You must move the object handle of the entry field to be used.

Output parameters

none

Remarks

This forms part of the clipboard group of functions consisting of Cut, Copy and Paste. In addition there are Select All and Delete functions to allow text in an entry field to be manipulated.

Note that both entry fields and multi-line entry fields may be referenced.

Sample code

* Select the entire text of an entry field

MOVE "S-CLPSEL" S-FR-MSG

MOVE-OBJECT-HANDLE EF-ENTRY-FIELD S-WINHAN

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CLPCUT, S-CLPCOPY, S-CLPPASTE, S-CLPDEL


S-DATE

The S-DATE function is used to call the date browse program.

Upon completion the function will return back to the next dialog function.

Input parameters

S-DATE1

You must move the existing date to this field.

Output parameters

S-DATE1

This contains the selected date when S-TO-PAR is spaces

S-TO-PAR

This field indicates whether the operator selected a date from the browse

Spaces – Yes date was selected

Remarks

This function is used to provide a date browse. It requires a date in the normal SYSPRO date format – this is a 6 digit format used to ask and print dates and can be:

DDMMYY

MMDDYY

YYMMDD

A year less than 50 is assumed to be 20xx. For example a year of '03' is assumed to be 2003.

Sample code

* Browse on date

MOVE "S-DATE" S-FR-MSG

MOVE DATE-FIELD S-DATE1

RETC

XIF= S-TO-PAR " " DATE-WAS-SELECTED

*

DATE-WAS-SELECTED

MOVE S-DATE1 DATE-FIELD

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-DATECOMP


S-DATECOMP

The S-DATECOMP function is used to compare two dates stored in SYSPRO's 6 digit date format.

Upon completion the function will return back to the next dialog function.

Input parameters

S-DATE2

Move the first date to be compared to this field.

S-DATE3

Move the second date to be compared to this field.

Output parameters

S-ERROR

This is a flag indicating whether S-DATE2 is later than S-DATE3

Not-spaces – S-DATE2 is later than S-DATE3

Remarks

This function is used to compare two dates in the normal SYSPRO date format – this is a 6 digit format used to ask and print dates and can be:

DDMMYY

MMDDYY

YYMMDD

A year less than 50 is assumed to be 20xx. For example a year of '03' is assumed to be 2003.

Sample code

* Compare two dates

MOVE "S-DATECOMP" S-FR-MSG

MOVE DATE-FIELD-1 S-DATE2

MOVE DATE-FIELD-2 S-DATE3

RETC

XIFNOT= S-ERROR " " S-DATE2-IS-LATER-THAN-S-DATE3

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-DATE


S-EXIT

The S-EXIT function is used to return to the calling program and tell it to branch to ENDJOB. This will cause the program to exit to it's calling program or the menu.

Input parameters

none

Output parameters

none

Remarks

As the screenset and program will be terminated no functions after this functions will be performed.

Care should be taken that the program does not perform any function in the ENDJOB routine.

Note that there is a S-EXITRUN function that allows you to exit the program and run another program.

Sample code

* Exit the program

MOVE "S-EXIT" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-EXITRUN, S-CALL, ENDJOB


S-EXITENC

The S-EXITENC function is used to return to the calling program and tell it to exit SYSPRO entirely.

The system will shutdown gracefully, closing all open files, updating job logging and logging-out the current operator.

Input parameters

none

Output parameters

none

Remarks

As the current screenset and program will be terminated no dialog functions after this functions will be performed.

Note that there is a S-EXIT function that simply exits the current program.

Sample code

* Exit SYSPRO entirely

MOVE "S-EXITENC" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-EXIT, S-CALL


S-EXITRUN

The S-EXITRUN function is used to return to the calling program and tell it to branch to ENDJOB. After the program has exited another program will be run.

Input parameters

S-FR-PAR

This field must contain the program to be run after the current program has exited.

Output parameters

none

Remarks

As the current screenset and program will be terminated no dialog functions after this functions will be performed.

Care should be taken that the program does not perform any function in the ENDJOB routine.

Note that there is a S-EXIT function that simply exits (it doesn't run another program).

Sample code

* Exit this program and run the Inventory Query

MOVE "S-EXITRUN" S-FR-MSG

MOVE "INVPEN" S-FR-PAR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-EXIT, S-CALL, ENDJOB


S-F2

The S-F2 function is identical to the logic used when the operator presses Shift+F2.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The Shift+F2 function calls the quick find program.

Sample code

* Handle the Shift+F2 function

MOVE "S-F2" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-F3

The S-F3 function is identical to the logic used when the operator presses Shift+F3.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The Shift+F3 function currently has no effect on the system.

Sample code

* Handle the Shift+F3 function

MOVE "S-F3" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-F4

The S-F4 function is identical to the logic used when the operator presses Shift+F4.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The Shift+F4 function toggles the print preview mode on/off

Sample code

* Handle the Shift+F4 function

MOVE "S-F4" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-F5

The S-F5 function is identical to the logic used when the operator presses Shift+F5.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The Shift+F5 function calls the Page setup dialog for the current printer.

Sample code

* Handle the Shift+F5 function

MOVE "S-F5" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-F6

The S-F6 function is identical to the logic used when the operator presses Shift+F6.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The Shift+F6 function calls the Print setup dialog – defaulting to the current printer.

Sample code

* Handle the Shift+F6 function

MOVE "S-F6" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-F7

The S-F7 function is identical to the logic used when the operator presses Shift+F7.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The Shift+F7 function calls the System Information program.

Sample code

* Handle the Shift+F7 function

MOVE "S-F7" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-F8

The S-F8 function is identical to the logic used when the operator presses Shift+F8.

Upon completion the function will return back to the next dialog function.

Input parameters

none

Output parameters

none

Remarks

The Shift+F8 function calls the program to save the current printer configuration against a report.

Sample code

* Handle the Shift+F8 function

MOVE "S-F8" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL


S-FILE-BRW

The S-FILE-BRW function is used to browse on Files or Folders. You can browse on Files/Folders on the Client or Server in a client/server environment.

Upon completion the function will return back to the next dialog function.

It is highly recommended that the S-FILE-BRW is used instead of a call directly to the dsdir program.

Input parameters

S-FR-PAR

File browsing - This is the default file name, including path, to be used for the browse. If there is no path then the base directory will be used as the default folder. Note that when using the File Open function that the file name shown in the browse will default to spaces.

Folder browsing - If you are using the Folder browse option then this field should be an existing folder with or without a trailing slash. If you leave this field blank then the Folder browse will default to the base folder.

S-FR-EXT

An indicator specifying the type of browse required

O – Open. The file must exist when returning from the browse

S – Save As. A warning will be displayed if the file already exists

B - Browse. Any file may be selected and no validation is performed on the file being selected.

F - Folder. This provides a Folder browse. The folder must exist when returning from the browse.

S-BRW1

A list of up to 10 x 3 character file extension that will be shown in the Files of Type selection box. For example 'BMPJPGGIF'. The first entry will be the default. An entry of '* ' means all files and will automatically be added if not supplied.

Remember files are case sensitive on Unix servers.

S-BRW2

An indicator specifying whether the file is on the Client or Server on a client/server environment. This has no effect on a mapped drive system.

S - Server (default)

C – Client

S-BRW3

This field allows you to specify a 30 character dialog box title. A default title will be provided if you leave this field blank.

Output parameters

S-TO-PAR

The selected file name. If a spacey file or folder name is returned it will be quoted.

If blank then the operator cancelled the browse.

Remarks

This function can be called from a program using the BROWSE-ON-FILES function.

Note that spacey file names generally must be enclosed in quotes when used for file handling functions. The browse will return any spacey file or folder names with surrounding quotes. However it is not necessary to supply quotes for the default File/Folder name passed.

It is highly recommended to supply a default extension as this makes it much easier for the operator to find the file they required. For example when looking for an Import file you could look for files with a txt extension. This is especially useful when navigating through various directories so that spurious files are not shown.

The user-interface shown when selecting File or Folder browsing is very similar to the standard Windows 2000/XP style common dialog control. Note however that it is not exactly the same. This browse dialog does allow browsing on both Client and Server systems - even Unix servers where applicable.

This proprietary file/folder browse currently has the following limits:

  • Only the first 3000 matching files per folder are shown

  • Only the first 200 sub-folders for the current folder are shown

  • No attempt is made to show the associated icon with each file shown

  • The Look in selection box shows more basic information (without icons) than the standard Windows Look in selection box

  • The context sensitive 'Right Click' to Copy, Delete, Rename, edit Properties etc has been disabled to prevent operators making changes

Sample code

* Browse/Select a bitmap file on the client

MOVE "S-FILE-BRW" S-FR-MSG

MOVE FILE-NAME S-FR-PAR

MOVE "O" S-FR-EXT

MOVE "BMP" S-BRW1

MOVE "C" S-BRW2

MOVE "Select Bitmap" S-BRW3

RETC

MOVE S-TO-PAR FILE-NAME

*

* Save As a txt file on the server

MOVE "S-FILE-BRW" S-FR-MSG

MOVE FILE-NAME S-FR-PAR

MOVE "S" S-FR-EXT

MOVE "txt" S-BRW1

MOVE "S" S-BRW2

RETC

MOVE S-TO-PAR FILE-NAME

*

* Browse for a txt file on client (may exist or not)

MOVE "S-FILE-BRW" S-FR-MSG

MOVE FILE-NAME S-FR-PAR

MOVE "B" S-FR-EXT

MOVE "txt" S-BRW1

MOVE "C" S-BRW2

RETC

MOVE S-TO-PAR FILE-NAME

*

* Select a Folder on the Server

MOVE "S-FILE-BRW" S-FR-MSG

MOVE FOLDER-NAME S-FR-PAR

MOVE "F" S-FR-EXT

MOVE "S" S-BRW2

RETC

MOVE S-TO-PAR FOLDER-NAME

*

* Select a Folder on the Client

MOVE "S-FILE-BRW" S-FR-MSG

MOVE FOLDER-NAME S-FR-PAR

MOVE "F" S-FR-EXT

MOVE "C" S-BRW2

MOVE "Select Folder on Client" S-BRW3

RETC

MOVE S-TO-PAR FOLDER-NAME

Requirements

Version: Included in Encore 5.0 and later. The ability to use the File Browse and Folder Browse (functions B and F) is only available in SYSPRO 6.0 Issue 006 and onwards.

Copybooks: standard

See also

spacey file names, BROWSE-ON-FILES


S-FORM-DEL

The S-FORM-DEL function is designed to allow a Custom form for a specific key to be deleted.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

S-FR-EXT

This is the key of the Custom form to be deleted. For example for form type STK this is the stock code.

Output parameters

none

Remarks

This function should be used to delete an existing Custom forms against a key field whenever a key field is deleted. Failure to do this may result in the key field being re-used and the Custom form data appearing against this new field.

Sample code

* Delete a custom form for a stock code

MOVE "S-FORM-DEL" S-FR-MSG

MOVE "STK" S-FR-PAR

MOVE STOCK-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, S-FORM-EDT, S-FORM-GET, S-FORM-TST


S-FORM-EDT

The S-FORM-EDT function is designed to allow the operator to enter new data onto a Custom form. If the form already exists then the existing data will be shown and the operator may amend it. If the form does not exist then a new one will be created with default values.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

S-FR-EXT

This is the key of the Custom form to be edited. For example for form type STK this is the stock code.

Output parameters

none

Remarks

This function is used to allow the operator to add or amend a Custom form.

See the Custom forms subject for details about how to add your own type of forms.

Sample code

* Edit a Custom form for a stock code

MOVE "S-FORM-EDT" S-FR-MSG

MOVE "STK" S-FR-PAR

MOVE STOCK-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, S-FORM-GET, S-FORM-DEL, S-FORM-TST


S-FORM-GET

The S-FORM-GET function is designed to retrieve a single field from a Custom form.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

S-FR-EXT

This is the key of the Custom form to be retrieved. For example for form type STK this is the stock code.

S-CALLOUT-PAR

This is the 6 character name of the custom form field to be retrieved.

Output parameters

S-CALLOUT-PAR

This is the returned value of the custom form field.

For numeric form fields this field contains an edited numeric value.

For date form fields this field contains an edited date.

S-ERROR

A status indicator.

Spaces - OK

Remarks

This function is used to retrieve a single form value from a custom form.

See the Custom forms subject for details about how to add your own type of forms.

Sample code

* Retrieve a form field called 'custom' for a stock code

MOVE "S-FORM-GET" S-FR-MSG

MOVE "STK" S-FR-PAR

MOVE STOCK-CODE S-FR-EXT

MOVE "custom" S-CALLOUT-PAR

RETC

IF= S-ERROR " " FIELD-RETURNED-PROC

* Field returned

FIELD-RETURNED-PROC

MOVE S-CALLOUT-PAR RETURNED-FIELD

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, S-FORM-EDT, S-FORM-DEL, S-FORM-TST


S-FORM-TST

The S-FORM-TST function is designed to allow a program to determine whether a custom form with mandatory fields has been successfully added.

Typically this is used by maintenance programs so that they can verify that a custom form has been added.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

S-FR-EXT

This is the key of the Custom form to be tested. For example for form type STK this is the stock code.

Output parameters

S-ERROR

This fields returns the status of the test.

Blank indicates that either there are no mandatory fields for this form or that all the mandatory fields have been defined for this key field.

Non-blank indicates that one or more mandatory fields have not yet been defined for the key field.

Remarks

This function is typically used by a maintenance program so that when adding a new item the maintenance program can ensure that a custom form with mandatory fields has been captured.

A mandatory field means a field that is set as not 'allowing spaces in field' or not 'allowing zeroes in field'.

See the Custom forms subject for details about how to add your own type of forms.

Sample code

* Test custom form for mandatory fields

MOVE "S-FORM-TST" S-FR-MSG

MOVE "STK" S-FR-PAR

MOVE STOCK-CODE S-FR-EXT

RETC

IFNOT= S-ERROR " " ASK-CUSTOM-FORM

Requirements

Version: Included in SYSPRO 6.0 Issue 006 and later.

Copybooks: standard

See also

Custom forms, S-FORM-GET, S-FORM-DEL, S-FORM-EDT, S-FORM-TST


S-HELP

The S-HELP function is used to call the on-line help system. You can pass a context number to be used.

This is typically called when the F1 key is pressed.

Upon completion the function will return back to the next dialog function.

Input parameters

S-HELP

This is a 4 digit context number to be used.

S-HLPTYP

An indicator specifying the type of help to be shown.

H The Help about Help topic is shown

I The Help Index is shown

C The Help Contents are shown

Blank The context help topic is shown

Output parameters

none

Remarks

This function is used to call the on-line help. It is called by the F1 function.

Sample code

* Call the on-line help

MOVE "S-HELP" S-FR-MSG

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-CALL, IMPHLP.IMP


S-LOWER

The S-LOWER function is used to convert a string to lowercase.

Upon completion the function will return back to the next dialog function.

Input parameters

S-CHR50A

The string to be converted – current maximum of 50 characters.

Output parameters

S-CHR50A

The converted string

Remarks

This routine simplifies generating text message based on user input.

There are similar routines S-UPLOWER and S-UPPER.

Sample code

* Convert entered string to lowercase

MOVE "S-LOWER" S-FR-MSG

MOVE ENTERED-STRING S-CHR50A

RETC

MOVE S-CHR50A FORMATTED-LOWERCASE

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-UPLOWER, S-UPPER


S-MDEL

The S-MDEL function is used to delete multimedia objects against a key field.

Upon completion the function will return back to the next dialog function.

This is part of the Multimedia facility that provides a consistent and easy to use interface to multimedia objects – such as bitmaps, sound clips, video and any OLE2 object.

Input parameters

S-FR-PAR

This is a 6 character code indicating the type of key. Existing standard key types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own multimedia objects should use key types beginning with USR.

S-FR-EXT

This is the key of the item to be deleted. For example for key type LDG this is the existing ledger code.

Output parameters

none

Remarks

Multimedia objects are a consistent and simple way to incorporate pictures, sound clips, video or almost any other type of object against a key field.

If you define a single multimedia object against a key field then the play function will automatically show/play the object. If there are multiple objects then you will be prompted for which one is to be viewed/played.

Third party developers can simply define a push button against a field and the dialog to call the multimedia functions.

Sample code

*

* Delete a map of a branch code

MOVE S-MDEL" S-FR-MSG

MOVE "USR-BR" S-FR-PAR

MOVE BRANCH-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Multimedia, S-MPLAY, S-MEDIT, S-MPATH


S-MEDIT

The S-MEDIT function is used to allow definition and editing of multimedia objects against a key field.

Upon completion the function will return back to the next dialog function.

This is part of the Multimedia facility that provides a consistent and easy to use interface to multimedia objects – such as bitmaps, sound clips, video and any OLE2 object.

Input parameters

S-FR-PAR

This is a 6 character code indicating the type of key. Existing standard key types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own multimedia objects should use key types beginning with USR.

S-FR-EXT

This is the key of the item to be edited. For example for key type LDG this is the existing ledger code.

Output parameters

none

Remarks

Multimedia objects are a consistent and simple way to incorporate pictures, sound clips, video or almost any other type of object against a key field.

If you define a single multimedia object against a key field using this function then the play function will automatically show/play the object. If there are multiple objects then you will be prompted for which one is to be viewed/played.

Third party developers can simply define a push button against a field and the dialog to call the multimedia functions.

Sample code

*

* Allow defining a map of a branch code

MOVE S-MEDIT" S-FR-MSG

MOVE "USR-BR" S-FR-PAR

MOVE BRANCH-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Multimedia, S-MPLAY, S-MDEL, S-MPATH


S-MPATH

The S-MPATH function is used to retrieve the path to a multimedia objects against a key field.

Upon completion the function will return back to the next dialog function.

This is part of the Multimedia facility that provides a consistent and easy to use interface to multimedia objects – such as bitmaps, sound clips, video and any OLE2 object.

Input parameters

S-FR-PAR

This is a 6 character code indicating the type of key. Existing standard key types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own multimedia objects should use key types beginning with USR.

S-FR-EXT

This is the key of the item to be edited. For example for key type LDG this is the existing ledger code.

Output parameters

none

Remarks

Multimedia objects are a consistent and simple way to incorporate pictures, sound clips, video or almost any other type of object against a key field.

This function can be used to return a path to a bitmap or other multimedia object.

Sample code

*

* Retrieve the path to a bitmap

MOVE S-MPATH" S-FR-MSG

MOVE "USR-BR" S-FR-PAR

MOVE BRANCH-CODE S-FR-EXT

RETC

MOVE S-TO-PAR BRANCH-BITMAP

Requirements

Version: Included in Encore 5.1 issue 004 and later.

Copybooks: standard

See also

Multimedia, S-MPLAY, S-MDEL, S-MEDIT


S-MPLAY

The S-MPLAY function is used to play or view an existing multimedia object defined against a key field.

Upon completion the function will return back to the next dialog function.

This is part of the Multimedia facility that provides a consistent and easy to use interface to multimedia objects – such as bitmaps, sound clips, video and any OLE2 object.

Input parameters

S-FR-PAR

This is a 6 character code indicating the type of key. Existing standard key types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own multimedia objects should use key types beginning with USR.

S-FR-EXT

This is the key of the item to be viewed/played. For example for key type LDG this is the existing ledger code.

Output parameters

none

Remarks

Multimedia objects are a consistent and simple way to incorporate pictures, sound clips, video or almost any other type of object against a key field.

If you define a single multimedia object against a key field then this play function will automatically show/play the object. If there are multiple objects then you will be prompted for which one is to be viewed/played.

Third party developers can simply define a push button against a field and the dialog to call the multimedia functions.

Sample code

* Play/view objects for Ledger code

MOVE "S-MPLAY" S-FR-MSG

MOVE "LDG" S-FR-PAR

MOVE LEDGER-CODE S-FR-EXT

RETC

*

* Play/view a user-defined map of the location of the branch

MOVE S-MPLAY" S-FR-MSG

MOVE "USR-BR" S-FR-PAR

MOVE BRANCH-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Multimedia, S-MEDIT, S-MDEL, S-MPATH


S-NCOPY

The S-NCOPY function is used to call the generic notepad and to have the notes for a key field duplicated against another key field.

Upon completion the function will return back to the next dialog function.

This is part of the Generic notepad facility that provides a consistent and easy to use interface to free format notes.

Input parameters

S-FR-PAR

This is a 6 character note type indicating the type of existing notes. Existing standard note types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own generic notes should use note types beginning with USR.

S-FR-EXT

This is the key of the generic notes to be copied. For example for note type LDG this is the existing ledger code.

S-BRW1

This is a 6 character note type indicating the new note type required. This can be the same as the source note type defined in S-FR-PAR or can be a new note type. Again third party developers defining their own generic notes should use note types beginning with USR.

S-BRW2

This is the new key required for the generic notes. This can be a different key from that defined in S-FR-EXT or can be the same key if copying notes to a different key type.

S-FR-DIR

This field can be used to flag that the current company is not to be used but instead that the notes are required system wide.

Blank - notes are required for the current company

S - System wide notes are required

R - Company specific notes are to be copied to system wide notes

Output parameters

none

Remarks

Generic notes are a consistent and simple way to allow the operator to view and edit notes against any key field.

This function is used for one of two purposes:

  1. If an item is being copied - such as a G/L code - then any notes against the original ledger code can be copied to the new ledger code. In this case the source type is LDG and the source ledger code is the original ledger code. The target note type will also be LDG and the target key will be the new ledger code.

  2. If an item is being 'transferred' from one type of item to another. For example when a sales order is converted to an invoice the generic notes could be transferred by copying the sales order type to an invoice note type.

Third party developers can simply define a push button against a field and the dialog to call the generic notes added to the push button.

See the other generic notepad functions for further usage.

Sample code

* Copy generic notes for sales order '123456' to an invoice '001234'

MOVE "S-NCOPY" S-FR-MSG

MOVE "ORD" S-FR-PAR

MOVE "123456" S-FR-EXT

MOVE "INV" S-BRW1

MOVE "001234" S-BRW2

RETC

Requirements

Version: Included in Encore 5.0 and later. The ability to specify System wide notes was only introduced into SYSPRO 6.0 issue 005.

Copybooks: standard

See also

Generic notepad, S-NDEL, S-NEDIT, S-NGRTF, S-NMOVE, S-NTEST, S-NVIEW


S-NDEL

The S-NDEL function is used to delete generic notes against a key field. These are defined using the S-NEDIT function. This function is generally used when an item is being deleted.

Upon completion the function will return back to the next dialog function.

This is part of the Generic notepad facility that provides a consistent and easy to use interface to free format notes.

Input parameters

S-FR-PAR

This is a 6 character note type indicating the type of notes. Existing standard note types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own generic notes should use note types beginning with USR.

S-FR-EXT

This is the key of the generic notes to be deleted. For example for note type LDG this is the existing ledger code.

S-FR-DIR

This field can be used to flag that the current company is not to be used but instead that the notes are required system wide.

Blank - notes are required for the current company

S - System wide notes are required

Output parameters

none

Remarks

Generic notes are a consistent and simple way to allow the operator to view and edit notes against any key field.

Third party developers can simply define a push button against a field and the dialog to call the generic notes added to the push button.

See the other generic notepad functions for further usage.

Sample code

* Delete generic notes for a ledger code

MOVE "S-NDEL" S-FR-MSG

MOVE "LDG" S-FR-PAR

MOVE LEDGER-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later. The ability to specify System wide notes was only introduced into SYSPRO 6.0 issue 005.

Copybooks: standard

See also

Generic notepad, S-NCOPY, S-NEDIT, S-NGRTF, S-NMOVE, S-NTEST, S-NVIEW


S-NGRTF

The S-NGRTF function is used to retrieve the full path name to any associated RTF file for the key field.

Upon completion the function will return back to the next dialog function.

This is part of the Generic notepad facility that provides a consistent and easy to use interface to free format notes.

Input parameters

S-FR-PAR

This is a 6 character note type indicating the type of notes. Existing standard note types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own generic notes should use note types beginning with USR.

S-FR-EXT

This is the key of the generic notes to be returned. For example for note type LDG this is the existing ledger code.

S-FR-DIR

This field can be used to flag that the current company is not to be used but instead that the notes are required system wide.

Blank - notes are required for the current company

S - System wide notes are required

Output parameters

S-TO-PAR

This field contains the full path name to the RTF file where any associated notes are stored. Blank is return if there are no notes associated with the key.

Remarks

Generic notes are a consistent and simple way to allow the operator to view and edit notes against any key field.

Third party developers can simply define a push button against a field and the dialog to call the generic notes added to the push button.

See the other generic notepad functions for further usage.

Sample code

* Retrieve RTF file name for a ledger code

MOVE "S-NGRTF" S-FR-MSG

MOVE "LDG" S-FR-PAR

MOVE LEDGER-CODE S-FR-EXT

RETC

MOVE S-TO-PAR RTF-FILENAME

Requirements

Version: Included in SYSPRO 6.0 issue 010 and later.

Copybooks: standard

See also

Generic notepad, S-NCOPY, S-NDEL, S-NEDIT, S-NMOVE, S-NTEST, S-NVIEW


S-NEDIT

The S-NEDIT function is used to call the generic notepad and allow the operator to view, edit and save notes against a key field.

Upon completion the function will return back to the next dialog function.

This is part of the Generic notepad facility that provides a consistent and easy to use interface to free format notes.

For structured fields see the Custom forms facility.

Input parameters

S-FR-PAR

This is a 6 character note type indicating the type of notes. Existing standard note types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own generic notes should use note types beginning with USR.

S-FR-EXT

This is the key of the generic notes to be edited. For example for note type LDG this is the existing ledger code.

S-FR-DIR

This field can be used to flag that the current company is not to be used but instead that the notes are required system wide.

Blank - notes are required for the current company

S - System wide notes are required

Output parameters

none

Remarks

Generic notes are a consistent and simple way to allow the operator to view and edit notes against any key field.

If you only want the operator to be able to view notes then use the S-NVIEW function.

Third party developers can simply define a push button against a field and the dialog to call the generic notes added to the push button.

See the other generic notepad functions for further usage.

Sample code

* Edit the generic notes for a ledger code

MOVE "S-NEDIT" S-FR-MSG

MOVE "LDG" S-FR-PAR

MOVE LEDGER-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later. The ability to specify System wide notes was only introduced into SYSPRO 6.0 issue 005.

Copybooks: standard

See also

Generic notepad, S-NCOPY, S-NDEL, S-NGRTF, S-NMOVE, S-NTEST, S-NVIEW


S-NMOVE

The S-NMOVE function is used to call the generic notepad and to have the notes for a key field renamed or to have the notes moved from one key type to another.

Upon completion the function will return back to the next dialog function.

This is part of the Generic notepad facility that provides a consistent and easy to use interface to free format notes.

Input parameters

S-FR-PAR

This is a 6 character note type indicating the type of existing notes. Existing standard note types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own generic notes should use note types beginning with USR.

S-FR-EXT

This is the key of the generic notes to be moved. For example for note type LDG this is the existing ledger code.

S-BRW1

This is a 6 character note type indicating the new note type required. This can be the same as the source note type defined in S-FR-PAR or can be a new note type. Again third party developers defining their own generic notes should use note types beginning with USR.

S-BRW2

This is the new key required for the generic notes. This can be a different key from that defined in S-FR-EXT or can be the same key if copying notes to a different key type.

S-FR-DIR

This field can be used to flag that the current company is not to be used but instead that the notes are required system wide.

Blank - notes are required for the current company

S - System wide notes are required

Output parameters

none

Remarks

Generic notes are a consistent and simple way to allow the operator to view and edit notes against any key field.

This function is used for one of two purposes:

  1. If an item is being renamed - such as a G/L code - then any notes against the original ledger code should be stored against the new ledger code. In this case the source type is LDG and the source ledger code is the original ledger code. The target note type will also be LDG and the target key will be the new ledger code.

  2. If an item is being moved from one type of item to another. In this case the note type can also be changed.

Third party developers can simply define a push button against a field and the dialog to call the generic notes added to the push button.

See the other generic notepad functions for further usage.

Sample code

* Move generic the notes from ledger code '001000' to '002000'

MOVE "S-NMOVE" S-FR-MSG

MOVE "LDG" S-FR-PAR

MOVE "001000" S-FR-EXT

MOVE "LDG" S-BRW1

MOVE "002000" S-BRW2

RETC

Requirements

Version: Included in Encore 5.0 and later. The ability to specify System wide notes was only introduced into SYSPRO 6.0 issue 005.

Copybooks: standard

See also

Generic notepad, S-NCOPY, S-NDEL, S-NEDIT, S-NGRTF, S-NTEST, S-NVIEW


S-NTEST

The S-NTEST function is used to call the generic notepad and to determine whether there are any notes defined against a key field.

Upon completion the function will return back to the next dialog function.

This is part of the Generic notepad facility that provides a consistent and easy to use interface to free format notes.

Input parameters

S-FR-PAR

This is a 6 character note type indicating the type of notes. Existing standard note types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own generic notes should use note types beginning with USR.

S-FR-EXT

This is the key of the generic notes to be tested. For example for note type LDG this is the existing ledger code.

S-FR-DIR

This field can be used to flag that the current company is not to be used but instead that the notes are required system wide.

Blank - notes are required for the current company

S - System wide notes are required

Output parameters

none

Remarks

Generic notes are a consistent and simple way to allow the operator to view and edit notes against any key field.

Third party developers can simply define a push button against a field and the dialog to call the generic notes added to the push button.

See the other generic notepad functions for further usage.

Sample code

* Test if there are any generic notes for a ledger code

MOVE "S-NTEST" S-FR-MSG

MOVE "LDG" S-FR-PAR

MOVE LEDGER-CODE S-FR-EXT

RETC

IFNOT= S-TO-PAR " " NOTES-EXIST-PROC

Requirements

Version: Included in Encore 5.0 and later. The ability to specify System wide notes was only introduced into SYSPRO 6.0 issue 005.

Copybooks: standard

See also

Generic notepad, S-NCOPY, S-NDEL, S-NEDIT, S-NGRTF, S-NMOVE, S-NVIEW


S-NVIEW

The S-NVIEW function is used to call the generic notepad and allow the operator to view notes against a key field. The operator will not be able to change the notes.

Upon completion the function will return back to the next dialog function.

This is part of the Generic notepad facility that provides a consistent and easy to use interface to free format notes.

Input parameters

S-FR-PAR

This is a 6 character note type indicating the type of notes. Existing standard note types include:

LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs
SERIAL | Serial numbers
LOT | Lot numbers

Third party developers defining their own generic notes should use note types beginning with USR.

S-FR-EXT

This is the key of the generic notes to be viewed. For example for note type LDG this is the existing ledger code.

S-FR-DIR

This field can be used to flag that the current company is not to be used but instead that the notes are required system wide.

Blank - notes are required for the current company

S - System wide notes are required

Output parameters

none

Remarks

Generic notes are a consistent and simple way to allow the operator to view and edit notes against any key field.

Third party developers can simply define a push button against a field and the dialog to call the generic notes added to the push button.

See the other generic notepad functions for further usage.

Sample code

* View (not edit) the generic notes for a ledger code

MOVE "S-NVIEW" S-FR-MSG

MOVE "LDG" S-FR-PAR

MOVE LEDGER-CODE S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later. The ability to specify System wide notes was only introduced into SYSPRO 6.0 issue 005.

Copybooks: standard

See also

Generic notepad, S-NCOPY, S-NDEL, S-NEDIT, S-NMOVE, S-NTEST


S-OSAFER

The S-OSAXFER function is used to transfer a file from the server system to the client PC using an ASCII mode transfer.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is the source file to be copied. It must be quoted if spacey.

S-FR-EXT

This is the target file to be copied. It must be quoted if spacey. See S-FR-DIR.

S-FR-DIR

This is a flag indicating the target location on the Client PC.

T – a temporary client file name will be generated. See Output parameters

B – the file will be transferred to the BASE directory

I – the file will be transferred to the BASE\BIN directory

F – S-FR-EXT contains the full path for the target file

Output parameters

S-ERROR

This will indicate whether the system was able to copy the file.

Spaces – Yes

S-TO-PAR

If the function T was defined in S-FR-DIR this contains the full path name of the temporary file generated on the client.

Remarks

If the required file names are spacey then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function is designed to be used to transfer text files from a Server to a Client. On a Unix Server environment the text file on the Server will be transferred to the Client by translating each linefeed to a carriage-return/linefeed pair.

On a Windows Server environment this translation is not required so this function will automatically perform the Binary mode copy function S-OSXFER.

Important: Note that this function handles a maximum file size of 60,000 bytes.

If you are developing for a Windows server environment then you should consider using the S-OSXFER as it does not have a file size limit.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy file version.txt to the client in ASCII mode

MOVE "S-OSAFER" S-FR-MSG

MOVE "version.txt" S-FR-PAR

MOVE "version.txt" S-FR-EXT

MOVE "F" S-FR-DIR

RETC

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 03 and later.

Copybooks: standard

See also

Spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, COPY-FILE-TO-CLIENT-ASCII, S-OSXFER, S-OSXFERS, S-OSAFERS


S-OSAFERS

The S-OSAFERS function is used to transfer a file from the client PC to the server system using an ASCII mode transfer.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is the source file to be copied. It must be quoted if spacey.

S-FR-EXT

This is the target file to be copied. It must be quoted if spacey.

Output parameters

S-ERROR

This will indicate whether the system was able to copy the file.

Spaces – Yes

Remarks

If the required file names are spacey then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function is designed to be used to transfer text files from a Client to a Server. On a Unix Server environment the text file on the Client will be transferred to the Server by translating each carriage-return/linefeed pair to a single linefeed.

On a Windows Server environment this translation is not required so this function will automatically perform the Binary mode copy function S-OSXFERS.

Important: Note that this function handles a maximum file size of 60,000 bytes.

If you are developing for a Windows server environment then you should consider using the S-OSXFERS as it does not have a file size limit.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy version.txt from the base on the client

* to the base on the server in ASCII mode

MOVE "S-OSAFERS" S-FR-MSG

MOVE "report.txt" S-FR-PAR

MOVE "report.txt" S-FR-EXT

RETC

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 03 and later.

Copybooks: standard

See also

Spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, COPY-FILE-TO-SERVER-ASCII, S-OSXFER, S-OSXFERS, S-OSAFER


S-OSCMD

The S-OSCMD function is used to call an operating system command or third party executable.

If you are running on a client/server system the command will be executed on the client. This is always a Windows based system.

Upon completion the function will return back to the next dialog function.

To call a SYSPRO program use S-CALL.

Input parameters

S-FR-PAR

This field defines the command to be executed. It can include a path if required.

Note that the Windows file associations will be used if the command is not an executable.

S-FR-EXT

This optional field can be used to define a 'start in' directory. The system will change to this directory, execute the command and return to the base directory.

Output parameters

none

Remarks

This function can used to run operating system commands (for example CALC.EXE). In addition any third party executable can be called. If the command is not included in the PATH then you may need to specify a start in directory.

This function recognises Windows file associations so calling a file with an appropriate extension will load the relevant executable to handle that file.

For example specifying C:\Temp\Report.doc will invoke Word or Wordpad as defined on your system automatically showing the Report.doc file.

When running on a client/server system this command is run from the client. This will always be a Windows environment. To run the command on the server use S-OSCMDS.

Asynchronous command

Note that this command will be run asynchronously. There is no easy method of forcing a command to be run synchronously but several techniques can be used.

For example if the executable is your own you could have it output a text file with it's results that could then be read by your application. Have the executable output an end-of-file terminator and if your program does not see this in the file it knows it has not yet finished.

Sample code

* Run the Windows calculator

MOVE "S-OSCMD" S-FR-MSG

MOVE "CALC.EXE" S-FR-PAR

RETC

* Run a third party executable in the C:\TEMP directory

MOVE "S-OSCMD" S-FR-MSG

MOVE "MYAPP.EXE" S-FR-PAR

MOVE "C:\TEMP" S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-OSCMDS, S-CALL, S-OSCMDS, EXECUTE-COMMAND-ON-CLIENT


S-OSCMDS

The S-OSCMDS function is used to call an operating system command or third party executable.

If you are running on a client/server system the command will be executed on the server. Remember that this may be a Windows or a Unix based system.

Upon completion the function will return back to the next dialog function.

To call a SYSPRO program use S-CALL.

Input parameters

S-FR-PAR

This field defines the command to be executed. It can include a path if required.

Note that on a Windows server environment the Windows file associations will be used if the command is not an executable.

S-FR-EXT

This optional field can be used to define a 'start in' directory. The system will change to this directory, execute the command and return to the base directory.

This parameter must be blank on a Unix server based system.

Output parameters

none

Remarks

This function is similar to S-OSCMD except that on a client/server environment this command runs on the server. Therefore it cannot be used to display any information or interact with the operator in any way.

In a client/server environment the server may be a Unix based system. You should ensure that only appropriate commands are used depending on the environment. Note that on a Unix environment you must not specify a start in directory.

If the command is not included in the PATH then you may need to specify a start in directory.

When running on a Windows based server this function recognises Windows file associations so calling a file with an appropriate extension will load the relevant executable to handle that file. Remember, however, that the command may not interact with the user.

Asynchronous command

Note that this command will be run asynchronously. There is no easy method of forcing a command to be run synchronously but several techniques can be used.

For example if the executable is your own you could have it output a text file with it's results that could then be read by your application. Have the executable output an end-of-file terminator and if your program does not see this in the file it knows it has not yet finished.

Sample code

* Run a 3rd party executable 'MYAPP' on the server

MOVE "S-OSCMDS" S-FR-MSG

MOVE "MYAPP.EXE" S-FR-PAR.

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-OSCMD, S-CALL, S-OSCMD, EXECUTE-COMMAND-ON-SERVER


S-OSCOPYS

The S-OSCOPYS function is used to copy one file to another on the server.

If you are running on a client/server system the command will be executed on the Server. Remember that may be a Windows or Unix based system.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This field contains the source file to be copied.

S-FR-EXT

This field contains the target file name.

Output parameters

none

Remarks

This function is used to copy one file to another on the server.

If using spacey file names you must surround the file names with quotes. See QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

Note that currently there is no equivalent function to copy files on the client.

Sample code

* Copy file ORIGINAL.TXT to NEW.TXT

MOVE "S-OSCOPYS" S-FR-MSG

MOVE "ORIGINAL.TXT" S-FR-PAR

MOVE "NEW.TXT" S-FR-EXT

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, COPY-FILE-ON-SERVER


S-OSDEL

The S-OSDEL function is used to delete a file on the client PC.

In a Client/Server environment this will be issued on the Client PC. This will always be a Windows environment.

Care must be taken to ensure that only appropriate files are deleted.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This field contains the file to be deleted.

Output parameters

none

Remarks

In a client/server system the command is executed on the client PC.

In a mapped drive system the command is executed on the client PC.

To delete a file on he server use the command S-OSDELS.

Sample code

* Delete file on client

MOVE "S-OSDEL" S-FR-MSG

MOVE "C:\TEMP\REPORT.TXT" S-FR-PAR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-OSDELS, DEL-FILE-ON-CLIENT


S-OSDELS

The S-OSDELS function is used to delete a file on the server system.

In a Client/Server environment this will be issued on the server. This may be a Unix or Windows environment.

Care must be taken to ensure that only appropriate files are deleted.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This field contains the file to be deleted.

Output parameters

none

Remarks

In a client/server system the command is executed on the server.

In a mapped drive system the command is executed on the client PC.

To delete a file on the client PC use the command S-OSDEL.

Sample code

* Delete report.txt in base folder on the server

MOVE "S-OSDELS" S-FR-MSG

MOVE "report.txt" S-FR-PAR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-OSDEL, DEL-FILE-ON-SERVER


S-OSGETD

The S-OSGETD function is used to retrieve the current directory. This is often used to save the current directory, change to another and later to restore the saved directory.

Important - standard SYSPRO programs must be run from the base directory.

If you are running on a client/server system the command will be executed on the Client. Remember that this is always a Windows based system.

Upon completion the function will return back to the next dialog function.

To retrieve the current directory on the server use S-OSGETDS.

Input parameters

none

Output parameters

S-TO-PAR

This field contains the current directory (on the client in a client/server environment).

Remarks

This function is used to retrieve the current directory.

On a client/server system this is the client directory.

Sample code

* Save the current directory, change to another and return

*

* Save current directory

MOVE "S-OSGETD" S-FR-MSG

RETC

MOVE S-TO-PAR SAVED-CLIENT-DIRECTORY.

*

* Now change to C:\TEMP

MOVE "S-OSSETD" S-FR-MSG

MOVE "C:\TEMP" S-FR-PAR

RETC

*

EXECUTE-PROCEDURE SOME-FUNCTION-IN-TEMP.

*

* Now restore the original directory

MOVE "S-OSSETD" S-FR-MSG

MOVE SAVED-CLIENT-DIRECTORY S-FR-PAR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-OSGETDS, S-OSSETD, GET-DIRECTORY-ON-CLIENT


S-OSGETDS

The S-OSGETDS function is used to retrieve the current directory. This is often used to save the current directory, change to another and later to restore the saved directory.

Important - standard SYSPRO programs must be run from the base directory.

If you are running on a client/server system the command will be executed on the Server. Remember that may be a Windows or Unix based system.

Upon completion the function will return back to the next dialog function.

To retrieve the current directory on the client use S-OSGETD.

Input parameters

none

Output parameters

S-TO-PAR

This field contains the current directory (on the server in a client/server environment).

Remarks

This function is used to retrieve the current directory.

On a client/server system this is the server directory.

Sample code

* Save the current directory, change to another and return

*

* Save current directory

MOVE "S-OSGETDS" S-FR-MSG

RETC

MOVE S-TO-PAR SAVED-SERVER-DIRECTORY.

*

* Now change to another directory

MOVE "S-OSSETDS" S-FR-MSG

MOVE NEW-DIRECTORY S-FR-PAR

RETC

*

EXECUTE-PROCEDURE SOME-FUNCTION-IN-TEMP.

*

* Now restore the original directory

MOVE "S-OSSETDS" S-FR-MSG

MOVE SAVED-SERVER-DIRECTORY S-FR-PAR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-OSGETD, S-OSSETDS, GET-DIRECTORY-ON-SERVER


S-OSMKDR

The S-OSMKDR function is used to create a folder on the client PC. It's parent must already exist and you must have appropriate permission.

If this command is used on a standalone/mapped system then this function is identical to S-OSMKDRS.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is the folder to be created. It must be quoted if spacey.

Output parameters

S-ERROR

This will indicate whether the system was able to create the folder.

Spaces – Yes

Remarks

If the required file names are spacey then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

You are responsible for ensuring that the parent folder already exists and that you have permission to create the folder required.

Use the function S-OSMKDRS to create a folder on the server.

Sample code

* Create folder on the server

MOVE "S-OSMKDR" S-FR-MSG

MOVE "C:\TEMP\SERVER" S-FR-PAR

RETC

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

Spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSMKDRS


S-OSMKDRS

SYSPRO SDK

Dialog Functions Reference

S-OSMKDR

The S-OSMKDRS function is used to create a folder on the server. It's parent must already exist and you must have appropriate permission.

If this command is used on a standalone/mapped system then this function is identical to S-OSMKDR.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is the folder to be created. It must be quoted if spacey.

Output parameters

S-ERROR

This will indicate whether the system was able to create the folder.

Spaces – Yes

Remarks

If the required file names are spacey then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

You are responsible for ensuring that the parent folder already exists and that you have permission to create the folder required.

Use the function S-OSMKDR to create a folder on the server.

Sample code

* Copy screenset INVPEN and associated user-controls to the client

MOVE "S-OSMKDR" S-FR-MSG

MOVE "C:\TEMP\CLIENT" S-FR-PAR

RETC

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

Spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSMKDR


S-OSSETD

The S-OSSETD function is used to set/change the current directory.

Important - standard SYSPRO programs must be run from the base directory. If you need to change the current directory you must save the original one using S-OSGETD and restore this after use.

If you are running on a client/server system the command will be executed on the Client. Remember that this is always a Windows based system.

Upon completion the function will return back to the next dialog function.

To set the current directory on the server use S-OSSETDS.

Input parameters

S-FR-PAR

This field contains the required directory.

Output parameters

none

Remarks

This function is used to set/change the current directory. Before changing a directory you must save the existing directory using S-OSGETD and restore this when you have finished – before returning back to a standard SYSPRO program or screenset.

If a spacey file name is used you must surround the file name with quotes. See QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

On a client/server system this sets the client directory.

Sample code

* Save the current directory, change to another and return

*

* Save current directory

MOVE "S-OSGETD" S-FR-MSG

RETC

MOVE S-TO-PAR SAVED-CLIENT-DIRECTORY.

*

* Now change to C:\TEMP

MOVE "S-OSSETD" S-FR-MSG

MOVE "C:\TEMP" S-FR-PAR

RETC

*

EXECUTE-PROCEDURE SOME-FUNCTION-IN-TEMP.

*

* Now restore the original directory

MOVE "S-OSSETD" S-FR-MSG

MOVE SAVED-CLIENT-DIRECTORY S-FR-PAR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file name, S-OSSETDS, S-OSGETD, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, SET-DIRECTORY-ON-CLIENT


S-OSSETDS

The S-OSSETDS function is used to set/change the current directory.

Important - standard SYSPRO programs must be run from the base directory.

If you are running on a client/server system the command will be executed on the Server. Remember that may be a Windows or Unix based system.

Upon completion the function will return back to the next dialog function.

To set the current directory on the client use S-OSSETD.

Input parameters

S-FR-PAR

This field contains the required directory.

Output parameters

none

Remarks

This function is used to set/change the current directory. Before changing a directory you must save the existing directory using S-OSGETDS and restore this when you have finished – before returning back to a standard SYSPRO program or screenset.

If a spacey file name is used you must surround the file name with quotes. See QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

On a client/server system this sets the server directory.

Sample code

* Save the current directory, change to another and return

*

* Save current directory

MOVE "S-OSGETDS" S-FR-MSG

RETC

MOVE S-TO-PAR SAVED-SERVER-DIRECTORY.

*

* Now change to another directory

MOVE "S-OSSETDS" S-FR-MSG

MOVE NEW-DIRECTORY S-FR-PAR

RETC

*

EXECUTE-PROCEDURE SOME-FUNCTION-IN-TEMP.

*

* Now restore the original directory

MOVE "S-OSSETDS" S-FR-MSG

MOVE SAVED-SERVER-DIRECTORY S-FR-PAR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file name, S-OSGETDS, S-OSSETD, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, SET-DIRECTORY-ON-SERVER


S-OSXFER

The S-OSXFER function is used to transfer a file from the server system to the client PC.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is the source file to be copied. It must be quoted if spacey.

S-FR-EXT

This is the target file to be copied. It must be quoted if spacey. See S-FR-DIR.

S-FR-DIR

This is a flag indicating the target location on the Client PC.

T – a temporary client file name will be generated. See Output parameters

S – the file will be copied to the screenset directory and any associated user controls in BASE\BIN will also be transferred

B – the file will be transferred to the BASE directory

I – the file will be transferred to the BASE\BIN directory

F – S-FR-EXT contains the full path for the target file

Output parameters

S-ERROR

This will indicate whether the system was able to copy the file.

Spaces – Yes

S-TO-PAR

If the function T was defined in S-FR-DIR this contains the full path name of the temporary file generated on the client.

Remarks

If the required file names are spacey then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function works by reading and transferring blocks of up to 60,000 bytes at a time across the network, reconstructing the target file on the client PC. Therefore files up to 60,000 bytes in size are transferred with a single network transition and will be fast. Files requiring relatively few network transitions will also be relatively fast. Large files (half a megabyte or more) may take a noticeable time to be transferred depending on the network speed.

Note that this function does not use any operating system commands and does not use ftp. The copy is a binary transfer therefore text files may or may not be accessible depending on the source operating system.

Note that client configuration can mean that several Client PC's are running on a remote LAN, often sharing drives and other resources.

Use the function S-OSXFERS to transfer a file from the Client PC to the server.

Binary mode

The files are transferred in a Binary mode. This means that each file is transferred exactly 'as is'. However if you intend to transfer a text file between Unix server and Windows client you may need to use the ASCII mode equivalent. See S-OSAFER and S-OSAFERS.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy screenset INVPEN and associated user-controls to the client

MOVE "S-OSXFER" S-FR-MSG

MOVE "INVPEN" S-FR-PAR

MOVE "S" S-FR-DIR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, COPY-FILE-TO-CLIENT, S-OSXFERS, S-OSAFER, S-OSAFERS


S-OSXFERS

The S-OSXFERS function is used to transfer a file from the client PC to the server system.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is the source file to be copied. It must be quoted if spacey.

S-FR-EXT

This is the target file to be copied. It must be quoted if spacey.

Output parameters

S-ERROR

This will indicate whether the system was able to copy the file.

Spaces – Yes

Remarks

If the required file names are spacey then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function works by reading and transferring blocks of up to 60,000 bytes at a time across the network, reconstructing the target file on the server system. Therefore files up to 60,000 bytes in size are transferred with a single network transition and will be fast. Files requiring relatively few network transitions will also be relatively fast. Large files (half a megabyte or more) may take a noticeable time to be transferred depending on the network speed.

Note that this function does not use any operating system commands and does not use ftp. The copy is a binary transfer therefore text files may or may not be accessible depending on the target operating system.

Use the function S-OSXFER to transfer a file from the server to the Client PC.

Binary mode

The files are transferred in a Binary mode. This means that each file is transferred exactly 'as is'. However if you intend to transfer a text file between Unix server and Windows client you may need to use the ASCII mode equivalent. See S-OSAFER and S-OSAFERS.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy report.txt from the base on the client

* to the base on the server

MOVE "S-OSXFERS" S-FR-MSG

MOVE "report.txt" S-FR-PAR

MOVE "report.txt" S-FR-EXT

RETC

Requirements

Version: Included in SYSPRO 6.0 issue 006 and later.

Copybooks: standard

See also

Spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, COPY-FILE-TO-SERVER, S-OSXFER, S-OSAFER, S-OSAFERS


S-PASSASK

The S-PASSASK function is used to request a password and to verify that the entered password matches an existing password.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character password type to identify the type of password being verified.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

S-FR-DIR

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

S-FR-EXT

This is the key of the item being protected.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

Output parameters

S-ERROR

A blank in this field means that the password was entered successfully.

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The S-PASSASK function allows the developer to prompt the operator for a password. The system will automatically verify the entered password and return a flag indicating whether the password was entered successfully. There is no need to provide any user-interface as this is entirely handled by the function.

Sample code

* Test the password for changing S/Order line price

MOVE "S-PASSASK" S-FR-MSG

MOVE "-SOR03" S-FR-PAR

RETC

IF= S-ERROR " " PASSWORD-ENTERED-CORRECTLY

*

* Test the password for an operator

MOVE "S-PASSASK" S-FR-MSG

MOVE "ADMOPR" S-FR-PAR

MOVE OPERATOR-CODE S-FR-EXT

RETC

IF= S-ERROR " " PASSWORD-ENTERED-CORRECTLY

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, S-PASSSET, S-PASSSETN, S-PASSVER, S-PASSINFO, S-PASSCTL


S-PASSCTL

The S-PASSCTL function is used to initialise your own password control record. This only has to be done once per password type.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character password type to identify the type of password.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

S-FR-DIR

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

Output parameters

none

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The S-PASSCTL function must be issued once to define your password type. Once this has been issued you can set, verify and delete passwords.

Sample code

* Set the password control for a credit note password

MOVE "S-PASSCTL" S-FR-MSG

MOVE "USRPAS" S-FR-DIR

RETC

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

password system, S-PASSASK, S-PASSSET, S-PASSSETN, S-PASSVER, S-PASSINFO


S-PASSINFO

The S-PASSINFO function is used to find out whether there is already a password defined. This can then be used by your application to ask a password.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character password type to identify the type of password being verified.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

S-FR-DIR

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

S-FR-EXT

This is the key of the item being verified.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

Output parameters

S-ERROR

This flag indicates whether there is a password against the key.

Y – Yes

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The S-PASSINFO function allows your application to determine whether a password exists for the type and key.

Sample code

* Verify if there is a password against a S/O line price

MOVE "S-PASSINFO" S-FR-MSG

MOVE "-SOR03" S-FR-PAR

RETC

IF= S-ERROR "Y" PASSWORD-EXISTS

*

* Verify if there is a password against an operator

MOVE "S-PASSINFO" S-FR-MSG

MOVE "ADMOPR" S-FR-PAR

MOVE OPERATOR-CODE S-FR-EXT

RETC

IF= S-ERROR "Y" PASSWORD-EXISTS

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, S-PASSASK, S-PASSSET, S-PASSSETN, S-PASSVER, S-PASSCTL


S-PASSSET

The S-PASSSET function is used to allow a new password to be defined. If there is an existing password this will need to be entered before a new one can be set.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character password type to identify the type of password being set.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

S-FR-DIR

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

S-FR-EXT

This is the key of the item being protected.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

Output parameters

S-ERROR

This flag indicates whether the operator set a new password.

Spaces – Yes

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The S-PASSSET function allows a new password to be defined. If any existing password exists then it must be entered before a new password can be set. The system will return a flag indicating whether a new password was set successfully.

Note that for operator passwords it is possible to configure various rules that must be satisfied before a new password is accepted.

Sample code

* Set the password for a S/Order line price change

MOVE "S-PASSSET" S-FR-MSG

MOVE "-SOR03" S-FR-PAR

RETC

IF= S-ERROR " " NEW-PASSWORD-WAS-SET

*

* Set the password for an operator

MOVE "S-PASSSET" S-FR-MSG

MOVE "ADMOPR" S-FR-PAR

MOVE OPERATOR-CODE S-FR-EXT

RETC

IF= S-ERROR " " NEW-PASSWORD-WAS-SET

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, S-PASSASK, S-PASSSETN, S-PASSVER, S-PASSINFO, S-PASSCTL


S-PASSSETN

The S-PASSSETN function is used to allow a new password to be defined. It assumes that your application has already asked for the new password – preferably reconfirming it. This function is then used to set the password without asking anything else.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character password type to identify the type of password being set.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

S-FR-DIR

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

S-FR-EXT

This is the key of the item being protected.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

S-BRW1

This is the unencrypted version of the password that the user has entered in your application. It can be up to 30 characters long.

Output parameters

none

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The S-PASSSETN function allows your application to request a new password and have the SYSPRO password system store it. Note that if there is any existing password then it will be silently overwritten. It is recommended that whenever you request a new password that the operator is asked to confirm the password to help prevent a typing mistake.

Sample code

* Set the password for S/Order line price change

MOVE "S-PASSSETN" S-FR-MSG

MOVE "-SOR03" S-FR-PAR

MOVE ASKED-PASSWORD S-BRW1

RETC

*

* Set the password for an operator

MOVE "S-PASSSETN" S-FR-MSG

MOVE "ADMOPR" S-FR-PAR

MOVE OPERATOR-CODE S-FR-EXT

MOVE ASKED-PASSWORD S-BRW1

RETC

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, S-PASSASK, S-PASSSET, S-PASSVER, S-PASSINFO, S-PASSCTL


S-PASSVER

The S-PASSVER function is used to verify a password that has been requested by your application against a previously set password.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Upon completion the function will return back to the next dialog function.

Input parameters

S-FR-PAR

This is a 6 character password type to identify the type of password being verified.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

S-FR-DIR

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

S-FR-EXT

This is the key of the item being verified.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

Output parameters

S-ERROR

This flag indicates whether the operator entered a valid password.

Spaces – Yes

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The S-PASSVER function allows a password prompted in your application to be verified against a previously defined password. The system will verify the password and return a flag indicating whether the password was entered successfully. If the password is incorrect this function will display an appropriate message.

The S-PASSASK function is more commonly use by systems wishing the check a password however existing systems often already prompt the operator for the password – in this case this function is more useful.

Sample code

* Verify entered password for S/Order line price change

MOVE "S-PASSVER" S-FR-MSG

MOVE "-SOR03" S-FR-PAR

MOVE CHANGE-LINE-PASSWORD

RETC

IF= S-ERROR " " PASSWORD-ENTERED-CORRECTLY

*

* Verify entered password for an operator

MOVE "S-PASSVER" S-FR-MSG

MOVE "ADMOPR" S-FR-PAR

MOVE OPERATOR-CODE S-FR-EXT

MOVE OPERATOR-PASSWORD S-BRW1

RETC

IF= S-ERROR " " PASSWORD-ENTERED-CORRECTLY

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, S-PASSASK, S-PASSSET, S-PASSSETN, S-PASSINFO, S-PASSCTL


S-UPLOWER

The S-UPLOWER function is used to convert a string in any case so that the initial character is capitalised and the rest is in lowercase.

Upon completion the function will return back to the next dialog function.

Input parameters

S-CHR50A

The string to be converted – current maximum of 50 characters.

Output parameters

S-CHR50A

The converted string

Remarks

This routine simplifies generating text message based on user input.

There are similar routines S-LOWER and S-UPPER.

Sample code

* Convert entered string to initial capital rest lowercase

MOVE "S-UPLOWER" S-FR-MSG

MOVE ENTERED-STRING S-CHR50A

RETC

MOVE S-CHR50A FORMATTED-DESCRIPTION

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-LOWER, S-UPPER


S-UPPER

The S-UPPER function is used to convert a string to uppercase.

Upon completion the function will return back to the next dialog function.

Input parameters

S-CHR50A

The string to be converted – current maximum of 50 characters.

Output parameters

S-CHR50A

The converted string

Remarks

This routine simplifies generating text message based on user input.

There are similar routines S-UPLOWER and S-LOWER.

Sample code

* Convert entered string to uppercase

MOVE "S-UPPER" S-FR-MSG

MOVE ENTERED-STRING S-CHR50A

RETC

MOVE S-CHR50A FORMATTED-UPPERCASE

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

S-UPLOWER, S-LOWER


User control overview

SYSPRO SDK

Dialog Functions Reference

Overview of User Controls

Introduction

The dialog system provides the most common Windows controls in an easy to use and fully integrated way. These are available just by clicking and dragging the object and inserting some Dialog to handle the interaction with the user.

However the Dialog system also allows virtually any Windows control available to be inserted and manipulated. These are called user controls.

Note that since SYSPRO 6.0 Issue 010 the user controls have been greatly enhanced over and above that used in prior versions of SYSPRO. It is recommended that you view the documents available on the Support Zone under the Developers section.

SYSPRO uses many user controls to enhance the user experience and include:

  • Listview

  • Toolbar

  • Docking pane

  • Status bar

  • Notepad

  • Image viewer

  • Internet explorer control

  • Display form

  • Entry form

Each user control is defined and manipulated using Dialog and often requires the development of an associated Net Express program to handle the interaction between the object, the screenset and the Windows system.

Syspro have developed a number of standard programs and copybooks to help simplify and standardise the development of these user control programs.

User control program overview

A user control program is linked specifically to an individual screenset. As several user controls can be defined against a single screenset the naming convention used is the first 6 characters are the screenset/program name follows by a two character mnemonic to indicate the type of user control.

For example the Stock code browse program (INVBST) has several user controls.

  • INVBSTTB The Toolbar control

  • INVBSTLV The Listview control

Each of these has a source code program defined in the \rnd60\source\binsrc directory and are compiled into the \rnd60\base\bin directory.

The screenset will invoke (call) the user control program from the base\bin directory. You do not need to specify the path as this is built-in to the SYSPRO executable.

Note that the user control programs usually require several data block fields to be defined for the interaction between the screenset and the user control program. Each user control is tied to the screenset data block version in a similar way to the screenset being tied to the program that was compiled with the data block. Note that the self-healing facility on a client/server environment that transfers screensets from the server to the client will automatically upload associated user controls to the client.

When adding a user control to a screenset remember to:

  • Import the relevant data block fields required (if any)

  • Click the Programmed controls Tab on the Dialog system definition window

  • Select and place the required control

  • Define the name etc against the control

  • Create your user control program (see documents on the Support Zone )

  • Compile your main program – when using the COMPILE.BAT command line compiler supplied with the SYSPRO SDK this will automatically compile associated user control programs

See Also

Support Zone document at www.syspro.com


PRO Function Overview

The PRO Function reference is a description of additional functions available over-and-above the standard functions described in the Function reference.

Use of PRO functions

The additional PRO functions are available by including a copybook in the PROCEDURE DIVISION with a .PRO extension and may require a copybook in the WORKING-STORAGE SECTION - generally with a .WRK extension.

See the subject PRO function list for links to the detailed functions available.

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Example use of a PRO Function

The following example assumes you require to calculate the number of days between two dates.

You must include the PROAGE.PRO and AGE.WRK copybooks to provide ageing functions. See the following code fragment. The lines marked 'age' indicate the inclusion of the two copybooks.

WORKING-STORAGE SECTION.

01 WHAT-STRING VALUE "@(#) Program version .000".

03 FILLER PIC X(25).

03 VERS PIC 9(3).

01 WHAT-DUMMY PIC X(2) VALUE X"0D0A".

*

01 DATE-1-CCYYMMDD PIC 9(8) VALUE 20041225.

* Lowest date in CCYYMMDD format

01 DATE-2-CCYYMMDD PIC 9(8) VALUE 20060101.

* Highest date in CCYYMMDD format

01 NO-OF-DAYS PIC S9(5).

* Number of days between days

*

age COPY "AGE.WRK". *> Supports ageing functions in PROAGE.PRO

COPY "SDK001.CPB". *> Dialog system data block copybook

COPY "DSCTL.WRK". *> Dialog system control block

*

COPY "STANDARD.WRK". *> Common working storage copybook

COPY "WWLINK.WRK". *> Common IMPSTD copybook

COPY "LNK.WRK". *> Copy LINK copybook

01 LNK2 PIC X. *> Dummy 2nd linkage copybook

*

LINKAGE SECTION.

COPY "LINK.WRK". *> Standard linkage

01 LINK2 PIC X. *> Dummy 2nd linkage

*

PROCEDURE DIVISION USING LINK, LINK2.

COPY "PROBEGIN.PRO".

age COPY "PROAGE.PRO". *> Provides ageing functions

*

** Calculate no of days between two dates

MOVE DATE-1-CCYYMMDD TO AGE-LOW-INT.

MOVE DATE-2-CCYYMMDD TO AGE-HIGH-INT.

PERFORM AGE-CYMD.

MOVE INVAGE TO NO-OF-DAYS.

*

See also

PRO function list, Function reference, PROAGE.PRO Overview


PRO Function List

The following table lists the PRO copybooks (together with their WRK copybooks) providing functions available from SYSPRO programs. See the topic PRO function overview for a generic description of how to use these functions.

PRO copybook | WRK copybook | Description
BROWSE.PRO | BROWSE.WRK | Browse program file handling functions
COMCRX.PRO | COMCRX.WRK | Create XML string functions
COMPAR.PRO | COMPAR.WRK | Parse XML functions
JNL.PRO | JNL.WRK | Setup amendment journal functions
LIST.PRO | LIST.WRK | Call interface to IMPLST/IMPLSC (SDK009)
PROABC.PRO | ABC.WRK | Activity Based Costing functions
PROAGE.PRO | AGE.WRK | Date ageing functions
PROARC.PRO | ARC.WRK | XML archive functions
PROASSET.PRO | ASSET.WRK | Asset calculation functions
PROBEGIN.PRO | STANDARD.WRK | Generic functions available in all programs
PROCACHE.PRO | CACHE.WRK | Generic data cache functions
PROCRE.PRO | CRE.WRK | A/P multi-period accounting functions
PROCSH.PRO | CSH.WRK | Cash Book multi-period accounting functions
PRODATES.PRO | DATES.WRK | Operation start/finish date calculation functions
PRODEB.PRO | DEB.WRK | A/R multi-period accounting functions
PRODEL.PRO | DEL.WRK | Delete index file functions
PROECC.PRO | ECC.WRK | Engineering change control functions
PROEDIT.PRO | EDIT.WRK | Price, cost and value edit functions
PROELE.PRO | ELE.WRK | Landed cost tracking calculate element line value functions
PROET.PRO | ET.WRK | Operation elapsed time calculation functions
PROEVT.PRO | IMPEVT.WRK | Event management functions
PROEXT.PRO | EXT.WRK | Price and value extension functions
PROFIFO.PRO | FIFO.WRK | FIFO and LIFO data update functions
PROFIND.PRO | FIND.WRK | Wildcard matching and masking functions
PROIAGED.PRO | IAGED.WRK | Inventory aged buckets update functions
PROIEXT.PRO | IEXT.WRK | Stocking cost extension functions
PROLOT.PRO | LOT.WRK | Test existence of lot for same item functions
PROMAL.PRO | MAL.WRK | Add material allocations to a job.
PROMC.PRO | {none} | Currency conversion functions
PRONEG.PRO | NEG.WRK | Negative stock functions
PROOPS.PRO | OPS.WRK | Operation value extension functions
PROPHANT.PRO | PHANT.WRK | Multi-level phantom parts in a Bill of Materials functions
PROPRD.PRO | PRD.WRK | Calculate Start/Finish dates using variable time parents.
PROPRT.PRO | {none} | Non-windows printer update functions
PROSCRAP.PRO | SCRAP.WRK | Determine start quantity required per operation
PROTAX.PRO | TAX.WRK | Tax functions
PROTAXE.PRO | TAX.WRK | USA tax functions
PROTERM.PRO | AGE.WRK | A/R invoice terms functions
PROTRG.PRO | IMPTRG.LNK | Trigger functions
PROVAL.PRO | IMPVAL.WRK | Check amount wording functions
PROVREL.PRO | VREL.WRK | Revision/release quantity calculation functions
PROWILD.PRO | WILD.WRK | Wildcard matching functions (native code programs)
PROWIQ.PRO | WIQ.WRK | Convert quantity per (6 dp) to inventory quantities (3 dp)
PROWRD.PRO | WRD.WRK | MS Word printing functions
PROWRDDE.PRO | WRD.WRK | MS Word template design functions
SQL.PRO | SQL.WRK | SQL Server optimization functions
VARIABLE.PRO | VARIABLE.WRK | Variable expression evaluation functions

Note that historically most of the .PRO copybooks also were prefixed with 'PRO' (e.g. PROAGE.PRO) however later copybooks do not always use the 'PRO' prefix (e.g. SQL.PRO).

The comments in each .PRO copybook generally give an indication about how they should be used.

See also

PRO function overview


BROWSE.PRO Overview

The functions available in BROWSE.PRO provide generic file handling logic for browse programs.

A browse program shows items is a listview allowing you to page up/down through the data 20 items at a time. Often there are maintenance functions available and sometimes a find, zoom and other functions.

The logic in BROWSE.PRO calls functions that you must define in your source code.

See the sample program SDKBTC for an example of how the browse functions should be used.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

BROWSE.WRK must be included in WORKING-STORAGE.

See also

PRO function overview, PRO function list


JNL.PRO Overview

The functions available in JNL.PRO provide logic to output Setup Amendment Journals and provide List functions for Setup programs.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

JNL.WRK must be included in WORKING-STORAGE.

List of available functions

The following functions are available.

Function name | Description
SETUPJNL-INITIALIZE | Initializes the Setup Amendment Journal functions. This must be performed before any of the other functions.
SETUPJNL-OUTPUT-AMENDMENT-JNL | Output the Amendment journal based on the setup parameter descriptions and the new/old values. Only changes are output.
SETUPJNL-LIST-REPORT-OPTIONS | Prints a list of all the setup parameters together with their new values.
SETUPJNL-OUTPUT-DETAIL | Use to pass a single setup parameter description together with an old or new value depending on whether the SETUPJNL-OLD or SETUPJNL-NEW has been last performed.
SETUPJNL-OUTPUT-TAB | Allows definition of the Tab page providing a heading for subsequent values.
SETUPJNL-OLD | Function to be performed before passing the setup parameter descriptions and their original values.
SETUPJNL-NEW | Function to be performed before passing the new values.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


LIST.PRO Overview

The functions available in LIST.PRO provides a call interface to the programs IMPLST and IMPLSC.

The sample program SDK009 provides a simple interface to the two main sets of functions as described below.

IMPLST Generic List Assignment

This program provides two panes, the first contains a list of available items and the second a list of assigned items. Your program passes these two lists as a set of initial values. The user interface allows you to move items from available to assigned and back as required. When 'saved' you are returned the two lists for you to save or for subsequent processing.

There is no practical limit to the number of items that can be passed or returned in either list.

IMPLSC Generic Checkbox Assignment

This program shows a single list of items that your program passes. Each items can be checked or unchecked. It's initial value is passed by your program. The user interface allows one or more items to be checked/unchecked. When 'saved' you are returned the list with the check/uncheck flag for you to save or for subsequent processing.

There is no practical limit to the number of items that can be passed.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

LIST.WRK must be included in WORKING-STORAGE.

List of available functions

The following functions are available for calling IMPLST.

Function name | Description
list-initialize | Function to be performed prior to invoking IMPLST or IMPLSC
list-add-to-available | Add item in implst-row to the list of available items
list-add-to-assigned | Add item in implst-row to the list of assigned items
list-call-lst-ui | Main function to call IMPLST passing available and assigned list
list-count-available | Return number of available items
list-count-assigned | Return number of assigned items
list-fetch-available | Retrieve a single available item into implst-row
list-fetch-assigned | Retrieve a single assigned item into implst-row
list-finalize-objects | Finalize available and assigned objects

Function name | Description
list-finalize-objects | Function to be performed prior to invoking IMPLST or IMPLSC
list-add-to-available | Add item in implst-row to the list of items
list-call-lsc-ui | Main function to call IMPLSC passing list of items
list-count-available | Return number of items
list-fetch-available | Retrieve a single item into implst-row
list-finalize-objects | Finalize list

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See the sample program SDK009 for a demonstration of using both of these sets of functions.

See also

PRO function overview, PRO function list


PROABC.PRO Overview

The function available in PROABC.PRO provides Activity Based Costing logic to read all elements per incidence per stock code into a table and to calculate the ABC cost per element.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

ABC.WRK must be included in WORKING-STORAGE.

The following files must be defined in your program and must be open.

- ABCSTR

- ABCELE

List of available functions

The following function is available.

Function name | Description
ABC-CALC-COST | Read all elements per incidence per stock code into a table and to calculate the ABC cost per element.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROAGE.PRO Overview

The functions available in PROAGE.PRO provide various date ageing and date calculation functions.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

AGE.WRK must be included in WORKING-STORAGE.

List of available functions

The following functions are available.

Function name

Description

AGE

Calculates the number of days between two dates in normal date format (either DDMMYY, MMDDYY or YYMMDD format).

In addition this calculation can use the A/R ageing setup options.

AGE-CYMD

Calculates the number of days between two dates in CCYYMMDD format.

In addition this calculation can use the A/R ageing setup options.

AGE-INVDAT-BY-INVAGE

Calculates a new date based on an existing date and a number of days offset - positive or negative.

AGE-INVDAT-BY-INVAGE-W

Calculates a new date based on an existing date and a number of days offset - positive or negative.

This function takes into account non-working days based on either the factory calendar or a work centre.

AGE-LOW-INT-BY-INVAGE

Calculates a new date based on an existing date and a number of days offset - positive or negative.

Input and output format dates are in CCYYMMDD format.

CHECK-WORKING-DAY1

Test if a date is a working or non-working day. If the date is non-working then you will be prompted to use a prior or future date instead.

CHECK-WORKING-DAY1-NEXT

Test if a date is a working or non-working day. If the date is non-working then the next working day will be selected without any user-interface.

CHECK-WORKING-DAY1-PREV

Test if a date is a working or non-working day. If the date is non-working then the previous working day will be selected without any user-interface.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

Note that the following functions built-in to PROBEGIN.PRO allow you to manipulate date-time values:

CALC-DATETIME-AGE

CALC-DATETIME-NEW-DATE

CALC-DATETIME-NEW-DATE-NUM

See also

PRO function overview, PRO function list, CALC-DATETIME-AGE, CALC-DATETIME-NEW-DATE, CALC-DATETIME-NEW-DATE-NUM


PROECC.PRO Overview

The functions available in PROECC.PRO provide various Engineering Change Control functions.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

ECC.WRK must be included in WORKING-STORAGE.

DEL.WRK must be included in the WORKING-STORAGE

BOMMST file must be defined in FILE-CONTROL and FILE SECTION

BOMOPS file must be defined in FILE-CONTROL and FILE SECTION

BOMNAR file must be defined in FILE-CONTROL and FILE SECTION

ARCBOM file must be defined in FILE-CONTROL and FILE SECTION

INVMST file must be defined in FILE-CONTROL and FILE SECTION

List of available functions

The following functions are available.

Function name

Description

ECC-BUILD-DATA

Checks whether the structure, operations and specific narrations have been archived for a revision/release of an ECC controlled stock code.

If it has been be archived then it calls a program COMRBO to extract the information from the archive XML document and creates temporary ISAM files with this information.

ECC-DELETE-DATA

Deletes any temporary files created by the ECC-BUILD-DATA function. This should be performed just before exiting the program.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PRODEL.PRO Overview

The functions available in PRODEL.PRO provide logic to delete an indexed file - this deletes both the data and index portion.

Note to delete a single file use the DELETE-WW-FILE-NAME function.

See the topic Deleting files for more information about deleting both ISAM and single files.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

DEL.WRK must be included in WORKING-STORAGE.

List of available functions

The following function is available.

Function name | Description
DELETE-INDEX-FILE | Used to delete an indexed file - both data and index portion. On Windows this deletes both a .DAT and .IDX file. On Unix this deletes the data file (no extension) and .idx file. The file must be closed before it can be deleted.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROET.PRO Overview

The functions available in PROET.PRO provide logic to calculate operation elapsed time, run time and unit capacity required for an operation.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

ET.WRK must be included in WORKING-STORAGE.

List of available functions

The following function is available.

Function name | Description
CALCULATE-ELAPSED-TIME | Calculates the elapsed time, the total run time required and the unit capacity required for an internal operation.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROFIND.PRO Overview

The functions available in PROFIND.PRO provide wildcard pattern matching functions. In addition a mask can be applied to matched patterns.

When including wildcard pattern matching functions to native code programs you should consider using PROWILD.PRO as this provides similar functionality but is completely compiled in the native code program - thus improving speed.

A sample program SDKPAT.CBL has been provided as part of the SDK to demonstrate use of the pattern matching routines.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

FIND.WRK must be included in WORKING-STORAGE.

List of available functions

The following functions are available.

Function name | Description
FIND-STARTUP | Initializes the Wildcard and filter pattern matching functions. This must be performed before any of the other functions.
TEST-IF-VALID-FILTER | Validates wildcard against currently allowed logic. Can be used to validate user entered wildcard.
TEST-IF-VALID-MASK | Validates wildcard and mask against currently allowed logic. Can be used to validate user entered values.
TEST-FILTER-AND-APPLY-MASK | This function is primarily used to determine whether a string matches a wildcard value. In addition, if the string matches the wildcard, a mask can be applied to the matched string.
TEST-FILTER-AND-APPLY-MASK-CI | This function allows you to determine whether string matches a wildcard value. The comparison is case-insensitive. Note that this case-insensitive function is only available from SYSPRO 6.0 issue 010 onwards.
TEST-FILTER2 | This function allows you to pass a 50 character wildcard and search a 255 character string. The comparison is case sensitive. Note that this function is only available from SYSPRO 6.1 onwards.
TEST-FILTER2-CI | This function allows you to pass a 50 character wildcard and search a 255 character string. The comparison is case-insensitive. Note that this function is only available from SYSPRO 6.1 onwards.
FIND-SHUTDOWN | Closes down the Wildcard functions and returns any resources used.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

General usage

Prior to SYSPRO 6.1 the most common code would be to first use the FIND-STARTUP - only needs to be performed once per run of the program - then prepare the fields FM-FILTER and FM-FIELD and perform the function TEST-FILTER-AND-APPLY-MASK-CI for a case insensitive pattern. The field FM-MATCH can be tested for 'Y' to check if the field matched the pattern. Finally use FIND-SHUTDOWN at ENDJOB to return any resources used.

Usage from SYSPRO 6.1 onwards

If you do not require to use the mask functions (common) and/or you need to search fields larger that the 60 characters provided previously then this can be simplified to use a second newer set of functions defined in the copybook.

See the following code fragment that is used to search the Contact full name field (100 characters) for the wildcard pattern stored in the field CMSQRO-ORG-SEARCH.

*

** Test full name

move cmsqro-org-search to fm2-filter. *> Can contain wildcard (eg 'john*')

move crmcon-full-name to fm2-field.

perform test-filter2-ci.

if fm2-match = "Y"

move "Y" to search-string-matched

go to test-search-end.

Note that this allows a 50 character wildcard and 255 character field to be used (old functions 30 and 60 characters).

Notes on allowable filters

The following table describes what filters are allowed:

Filter | Note
ABC | No wildcards - field must match filter exactly
ABC* | Field must start 'ABC' and can be any length
*ABC | Field must end 'ABC' and can be any length
*ABC* | Field must contain 'ABC' and can be any length
ABC*BCD | Field must start 'ABC' and end 'BCD'

Note 1: In all cases the string 'ABC' can contain '?' to represent any single character

Note 2: If a '?' is used at the beginning or end of a filter then this will only match a non-blank character

Note 3: '*ABC*' is the only case where 2 x '*' may be entered

Note 4: 'ABC*BCD' does NOT match 'ABCD'

Note 5: You cannot use a file pattern such as 'INV*.*' to match a program such as 'INVPEN.INT' as this does NOT conform to the rule about 2 x'*'. However 'INV???.*' does work as it only has a single '*'.

Notes on search SQL tables

When searching for alphabetic information in tables you should strongly consider using SQL optimized code on SQL server tables. This is done using the SQL LIKE clause.

See the function SQL-GENERATE-WHERE-LIKE for more information about how this function can be used. It supports the same wildcard pattern matching characters as used in the function defined in PROFIND.PRO.

See also

PRO function overview, PRO function list, SQL-GENERATE-WHERE-LIKE


PROMAL.PRO Overview

The functions available in PROMAL.PRO provide logic to add material allocations to a job.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

MAL.WRK must be defined in WORKING-STORAGE.

WIPMAL file must be defined in FILE-CONTROL and FILE SECTION and open depending on function required.

MRPSML file must be defined in FILE-CONTROL and FILE SECTION and open depending on function required.

MRPSML file must be defined in FILE-CONTROL and FILE SECTION and open depending on function required.

List of available functions

The following functions are available.

Function name | Description
WIPMAL-ADD-REC | Calculates the next allocation line number and adds the record to the live job material allocation file.
MRPMAL-ADD-REC | Calculates the next allocation line number and adds the record to the snapshot job material allocation file.
MRPSML-ADD-REC | Calculates the next allocation line number and adds the record to the snapshot suggested job material allocation file.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROOPS.PRO Overview

The functions available in PROOPS.PRO provide operation value extension functions.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

OPS.WRK must be included in WORKING-STORAGE.

WIPLAL file must be defined in FILE-CONTROL and FILE SECTION if you wish to use CALC-OP-OFLOW function.

List of available functions

The following functions are available.

Function name | Description
CALCULATE-OP-VALUE | Calculates the value or cost of an internal operation.
CALCULATE-OP-TIME | Calculates the planned times for an internal operation.
CALCULATE-OP-OFLOW | Checks for time overflows when adding times to those already posted against a job’s labor allocation entry (this must be already read).

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROPHANT.PRO Overview

The functions available in PROPHANT.PRO provide logic to process multi-level phantoms in a Bill of Materials.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

PHANT.WRK must be defined in WORKING-STORAGE.

INVMST file must be defined in FILE-CONTROL and FILE SECTION and open.

BOMMST file must be defined in FILE-CONTROL and FILE SECTION and open.

List of available functions

The following function is available.

Function name | Description
GET-PHANTOM-COMPONENT | Reads through a phantom part’s structure and returns components attached that are not phantoms.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROPRD.PRO Overview

The functions available in PROPRD.PRO provide various date ageing and date calculation functions.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

PRD.WRK must be defined in WORKING-STORAGE.

PROAGE.PRO must be defined in the PROCEDURE DIVISION.

List of available functions

The following functions are available.

Function name | Description
CALC-START-FINISH-DATES | Calculates up to 100 start/finish dates starting at a date passed.
CALC-START-FINISH | Routine to return the start/finish date for a given period (Note periods start at zero) based on the results of the CALC-START-FINISH-DATES function.
CALC-PRD-NUMBER | Routine to calculate which period a date falls into based on the dates calculated in CALC-START-FINISH-DATES.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROPRT.PRO Overview

The functions available in PROPRT.PRO provide logic to update the printer linkage fields after reading a non-Windows printer from the ADMPRT data file.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

ADMPRT must be defined and the non-Windows printer must have been read.

ADMPRA must be defined and the file must be open.

The field L-PRINTER-T must be set to 'E'.

List of available functions

The following function is available.

Function name | Description
UPDATE-PRINTER-LINKAGE | Updates the printer linkage for non-Windows printers.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROSCRAP.PRO Overview

The functions available in PROSCRAP.PRO provide logic to calculate the start quantity required at an operation, taking progressive scrap into account. In addition a rounding facility is provided.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

SCRAP.WRK must be defined in WORKING-STORAGE.

List of available functions

The following functions are available.

Function name | Description
PRG-ROUND-CALC-QTY | Rounds a given quantity to the required number of decimal places.
PRG-GROSS-SCRAP-CALC | Calculates the start quantity for an operation if the quantity entered for the parent (or EBQ) is the NET quantity required.
PRG-NET-SCRAP-CALC | Calculates the start quantity for an operation if the quantity entered for the parent (or EBQ) is the GROSS quantity required.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROTRG.PRO Overview

The functions available in PROTRG.PRO provide logic to handle trigger points in SYSPRO applications.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

IMPTRG.LNK must be included in WORKING-STORAGE.

List of available functions

The following function is available.

Function name

Description

TRIGGER-POINT

Used to indicate that a trigger point has been reached and if configured that the trigger should be fired.

The program should call IMPTRG with a 'T' in the IMPTRG-FUNCTION when it starts. This sets up the IMPTRG-LINKAGE fields for subsequent TRIGGER-POINT function calls.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROVREL.PRO Overview

The functions available in PROVREL.PRO provide revision/release quantity calculation functions.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

VREL.WRK must be defined in WORKING-STORAGE.

LOTDET file must be defined in FILE-CONTROL and FILE SECTION and open.

INVINC file must be defined in FILE-CONTROL and FILE SECTION and open.

SORDET file must be defined in FILE-CONTROL and FILE SECTION and open.

SORMST file must be defined in FILE-CONTROL and FILE SECTION and open.

PORDET file must be defined in FILE-CONTROL and FILE SECTION and open.

PORMST file must be defined in FILE-CONTROL and FILE SECTION and open.

WIPMAL file must be defined in FILE-CONTROL and FILE SECTION and open.

WIPMST file must be defined in FILE-CONTROL and FILE SECTION and open.

GTRDET file must be defined in FILE-CONTROL and FILE SECTION and open.

GTRMST file must be defined in FILE-CONTROL and FILE SECTION and open.

MDNDET file must be defined in FILE-CONTROL and FILE SECTION and open.

MDNMST file must be defined in FILE-CONTROL and FILE SECTION and open.

PROEXT.PRO must be defined in PROCEDURE DIVISION.

PROAGE.PRO must be defined in PROCEDURE DIVISION.

PROWIQ.PRO must be defined in PROCEDURE DIVISION.

SQL.PRO must be defined in PROCEDURE DIVISION.

List of available functions

The following function is available.

Function name | Description
VREL-ECC-GET-QTY | Reads through various files obtaining quantities for an ECC controlled item.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROWIQ.PRO Overview

The functions available in PROWIQ.PRO provide logic to convert quantity per (6 decimals) to inventory quantities (3 decimals).

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

WIQ.WRK must be defined in WORKING-STORAGE.

List of available functions

The following function is available.

Function name | Description
WIP-INV-QTY-CALC | Multiplies out a component quantity by the parent quantity and converts the result to the correct inventory decimal places.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


PROWILD.PRO Overview

The functions available in PROWILD.PRO provide wildcard pattern matching functions. In addition a mask can be applied to matched patterns.

This function is primarily designed to be used in native code programs as all the logic is included in the .PRO copybook.

If you are developing an intermediate code program then you should consider using the PROFIND.PRO copybook which provides similar functions but calls a separate program to handle the functions.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

FIND.WRK must be included in WORKING-STORAGE.

List of available functions

The following functions are available.

Function name | Description
TEST-IF-VALID-FILTER | Validates wildcard against currently allowed logic. Can be used to validate user entered wildcard.
TEST-IF-VALID-MASK | Validates wildcard and mask against currently allowed logic. Can be used to validate user entered values.
TEST-FILTER-AND-APPLY-MASK | This function is primarily used to determine whether a string matches a wildcard value. In addition, if the string matches the wildcard, a mask can be applied to the matched string.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


SQL.PRO Overview

The functions available in SQL.PRO provide access to SQL Server database access functions.

These functions are used to access the database using optimised SQL statements. These can include SELECT, UPDATE and DELETE statements.

For more information about using these functions and other SQL Server concepts see the topics, SQL Server Tuning and SQL Server Tuning code.

Generic use of functions

Generally each function should be used by:

  1. Setting up any Input parameters to ensure the correct settings are passed to the function.

  2. PERFORM the function

  3. Retrieve and use any Output parameters as necessary

Dependencies

SQL.WRK must be included in WORKING-STORAGE.

List of available functions

The following functions are available.

Function name | Description
SQL-INITIALISE | Initializes the SQL Server optimization functions. This must be performed before any of the other functions. You must use the SQL-SHUTDOWN function to terminate the SQL Server optimization logic.
SQL-FLAG-SETUP | Determine whether the current company is SQL Server or ISAM based. Use at the beginning of the program to configure the SQL-FLAG field.
SQL-BUILD-COMMAND | Build a SQL Server SELECT statement. Use SQL-FETCH-ROW to return the result set.
SQL-FETCH-ROW | Retrieve a single row from the result set configured with the SQL-BUILD-COMMAND function.
SQL-DEFINE-GROUP-BY | Allows definition of a GROUP BY clause to the SELECT statement. This must be performed before the SQL-BUILD-COMMAND function is used.
SQL-DEFINE-HAVING | Allows definition of a HAVING clause to the SELECT statement. This must be performed before the SQL-BUILD-COMMAND function is used.
SQL-COMPLEX-COLUMN | Allows definition of a column name (or column definition) with more that 20 characters. The word '{complex}' must be moved to the equivalent column to represent the column position.
SQL-GET-VAL | Allows retrieving an alphanumeric string longer than 40 characters from the result set.
SQL-UPDATE-ROWS | Used to build and execute a SQL UPDATE command.
SQL-DELETE-ROWS | Used to build and execute a SQL DELETE command.
SQL-DEFINE-DELETE-FROM | Allows definition of a FROM clause to the DELETE statement. This must be performed before the SQL-DELETE-ROWS function is used.
SQL-EXECUTE-COMMAND | Allows any SQL Server command to be executed. No results can be returned except a status flag.
SQL-COUNT-ROWS | Used to count the number of rows in a table.
SQL-CHECK-TABLE-EXISTS | Used to validate whether a table exists in the current database.
SQL-CHECK-COLUMN-EXISTS | Used to validate whether a table.column exists in the current database.
SQL-SHUTDOWN | Closes down the SQL Server optimization functions and returns any resources used.
SQL-CON-NEXT | Used to set the SQL-CX1 pointer to the next free character in the condition field - SQL-CON.
SQL-CON-END | Used to remove any trailing 'AND' or 'OR' in the condition field - SQL-CON.

Note that it is not recommended to use any other functions in the copybook as they are subject to change.

See also

PRO function overview, PRO function list


Function Reference Overview

Introduction

The Function reference is a detailed description of each function available from SYSPRO programs. These are available from the PROBEGIN.PRO copybook included in all SYSPRO programs.

See the topics Functions by name and Functions by type for a complete list of functions.

To assist in ensuring consistency the function reference topics are divided into various sections. These are listed below with an overview of what is covered in each section.

Generally each function should be used by:

1. Setting up any Input parameters to ensure the correct settings are passed to the function.

2. PERFORM the function

3. Retrieve and use any Output parameters as necessary

For additional functions available by including PRO and WRK copybooks in your source code see the topics PRO function overview and PRO function list.

Input parameters

The input parameters are a list of the possible fields that should be setup before the function is performed. These usually reside in LINK.WRK or WWLINK.WRK.

Output parameters

The output parameters are a list of the possible fields that are returned after the function has been performed. These are usually returned in LINK.WRK or WWLINK.WRK.

Remarks

The remarks section contains a detailed explanation of how the function should be used together with any additional information relating to the function or the possible settings.

Sample code

The Sample code section includes a code fragment that demonstrates how to use the function. This could be copied and pasted into a source code program and changed as required.

Requirements

Version: This section indicates the version of SYSPRO or Encore required to use the function.

Copybooks: This section indicates which copybooks are required to perform the function. For the majority of the functions this says Standard which indicates that the normal copybooks used in every SYSPRO program are required - this includes:

  • PROBEGIN.PRO

  • LINK.WRK

  • STANDARD.WRK

  • WWLINK.WRK

  • ??????.CPB where ?????? is the name of the program

See the description of the sample program SDK001 to see how these should be used.

See also

This section contains links to related topics - for example Functions by name, Functions by type, sample program SDK001, PROBEGIN.PRO


Functions by name

SYSPRO SDK

Function Reference

The following is an alphabetical list of standard functions available from PROBEGIN.PRO.

A Functions

ADD-CHG-DEL-NOT-FOUND

ADD-PASSWORD-CTL

ASK-BRW-MAINT-CONFIRM-MBOX

ASK-BRW-MAINT-RET-MBOX

ASK-PASSWORD

B Functions

BEGIN-TRANSACTION

BROWSE-ON-FILES

BUILD-BITMAP-NAME

BUILD-FILE-NAME

BUILD-PROGRAM-NAME

BUILD-SCREENSET-NAME

BUILD-STP-NAME

BUILD-TMPFIL

BUILD-TMPFIL-NO-PATH

BUILD-TMPFIL-NO-PATH-USER-EXT

BUILD-TMPFIL-USER-EXT

BUILD-USR-FILE-NAME

C Functions

CALC-DATETIME-AGE

CALC-DATETIME-NEW-DATE

CALC-DATETIME-NEW-DATE-NUM

CALC-DAY-OF-WEEK

CALL-BO-ADD

CALL-BO-BUILD

CALL-BO-DELETE

CALL-BO-POST

CALL-BO-POST-RTGL

CALL-BO-QUERY

CALL-BO-UPDATE

CALL-DS

CALL-PROGRAM

CALL-PROGRAM-NO-CANCEL

CANCEL-PROGRAM

CANNOT-RUN-STANDALONE

CHECK-FILE-EXISTS

CHECK-FILE-EXISTS-ON-CLIENT

CHECK-FILES-IN-USE

CHECK-IF-OPER-BELONGS-TO-GROUP

CHECK-MAINTENANCE

CHECK-MAINTENANCE-OTHER-PROG

CHECK-SHARED-TABLE

CHECK-SHARED-TYPE

CHECK-USER-STILL-VALID

CLEAR-AP-PAY-LOCK

CLEAR-FORCE-CHANGE-PASSWORD

CLEAR-GL-ENT-LOCK

CLEAR-WIP-TRIAL-LOCK

CLR-PRINT-BY-FUNCTION

CMS-READ-CONTACT-GUID-FRM-NAME

CMS-READ-CONTACT-NAME-FRM-GUID

COM-ERROR-MSG

COMER

COMMIT-TRANSACTION

CONTROL-ERROR

CONVERT-ASCII-TO-HEX

CONVERT-GUID16-TO-GUID38

CONVERT-GUID38-TO-GUID16

CONVERT-HEX-TO-ASCII

CONVERT-LOWER-CASE

CONVERT-PATH-PRINT

CONVERT-UPPER-CASE

CONVERT-UPPER-LOWER

COPY-FILE-ON-SERVER

COPY-FILE-TO-CLIENT

COPY-FILE-TO-CLIENT-ASCII

COPY-FILE-TO-SERVER

COPY-FILE-TO-SERVER-ASCII

CREATE-DIRECTORY-ON-CLIENT

CREATE-DIRECTORY-ON-SERVER

CUSTOM-FORM-COPY

CUSTOM-FORM-COPY-TYPE

CUSTOM-FORM-DEL

CUSTOM-FORM-EDIT

CUSTOM-FORM-GET

CUSTOM-FORM-READ-ALL

CUSTOM-FORM-READ-ALL-DESC

CUSTOM-FORM-READ-CTL

CUSTOM-FORM-TEST

D Functions

DATE-COMPARE

DATE-COMPARE-YMD

DATE-FROM-CYMD

DATE-NORM

DATE-TO-CYMD

DATE-YMD

DECREMENT-LINE-X5

DECRYPT-CIPHER-TEXT

DEL-FILE-ON-CLIENT

DEL-FILE-ON-SERVER

DEL-PASSWORD

DELETE-AP-PAY-LOCK

DELETE-WW-FILE-NAME

E Functions

EDIT-DATE-TO-USER-FORMAT

EDIT-DATE-TO-USER-FORMAT-CYMD

EDIT-DATE-YYYY-MM-DD

EDIT-FORMATTED-DATE

EDIT-NO-LEADING-SPACES

EDIT-QUANTITY

EDIT-QUANTITY-LIST

EDIT-REPORT-DATE

ENCRYPT-PLAIN-TEXT

EXPAND-LINK-EXTRA

EXPAND-WW-FILE-NAME

EXECUTE-COMMAND-ON-CLIENT

EXECUTE-COMMAND-ON-SERVER

F Functions

FILTER-ACCESS

FILTER-ACCESS-APBR

FILTER-ACCESS-ARBR

FILTER-ACCESS-BANK

FILTER-ACCESS-CUS (e.net only)

FILTER-ACCESS-FIELD

FILTER-ACCESS-JOBCL

FILTER-ACCESS-REP

FILTER-ACCESS-TT

FILTER-ACCESS-WH

FMT-POST

G Functions

GENERATE-GUID

GENERATE-VALID-FILE-NAME

GET-AP-PAY-LOCK

GET-CLIENT-IMPACT-INI

GET-COMPANY-LIST-ALL

GET-COMPANY-LIST-ALL-COMMA

GET-COMPANY-LIST-INV

GET-COMPANY-LIST-INV-COMMA

GET-COMPUTER-DATE-TIME

GET-DATABASE-NAME

GET-DIRECTORY-ON-CLIENT

GET-DIRECTORY-ON-SERVER

GET-ENVIRONMENT-STRING

GET-GL-ENT-LOCK-EXCLUSIVE

GET-GL-ENT-LOCK-SHARED

GET-GROUPS-FOR-OPERATOR

GET-PASSWORD-INFO

GET-PRINT-BY-FUNCTION

GET-STD-ENCORE-PATH

GET-STD-SYSPRO-PATH

GET-WIP-TRIAL-LOCK-EXCLUSIVE

H Functions

HTML-TO-TEXT

I Functions

INCREMENT-LINE-X5

INVOKE-MESSAGE-BOX

INVOKE-MESSAGE-BOX-RESET

INVOKE-TASK-DIALOG

IS-DATE-VALID

IS-DATE-VALID-CYMD

IS-LEAP-YEAR

J Functions

JOB-MESSAGE

JOB-MESSAGE-DETAIL

JOB-MESSAGE-IF-BLANK

JOB-MESSAGE-READ

JOB-MESSAGE-TRANSACT

L Functions

LOOK-UP-ERROR

LOOKUP-MSG

M Functions

MODULE-NOT-INSTALLED

MULTIMEDIA-DELETE-ALL

MULTIMEDIA-GET-PATH

MULTIMEDIA-PLAY

N Functions

NULL-TASK

NULL-TERMINATE-STRING

NUMB-CHECK

O Functions

OBJECT-COUNT-END

OBJECT-COUNT-START

OUTPUT-DEBUG-LOG

OUTPUT-SYSTEM-JOB-LOG

P Functions

PRINT-BOLD-OFF

PRINT-BOLD-ON

PRINT-CLOSE

PRINT-CLOSE-NO-PRINT

PRINT-HOF-UNDERLINE

PRINT-HORIZONTAL-LINE

PRINT-OPEN

PROCESS-WW-LOGIC-TAB

Q Functions

QUIT-DS

QUIT-DS-ALWAYS

QUOTE-VALID-FILE-NAME

R Functions

READ-COMPANY-PATHS

REFRESH-SECURITY-SETTINGS

REGISTER-MSG

RESET-TICKOVER

RESOURCE-LOCK-ADD

RESOURCE-LOCK-ADD-MSG

RESOURCE-LOCK-DELETE

RESOURCE-LOCK-TEST

RESOURCE-LOCK-TEST-MSG

RETRIEVE-PRINT-BY-FUNCTION

ROLLBACK-TRANSACTION

S Functions

SERV

SERVREQ

SET-DIRECTORY-ON-CLIENT

SET-DIRECTORY-ON-SERVER

SET-FORCE-CHANGE-PASSWORD

SET-PASSWORD

SET-PASSWORD-NO-ASK

SET-PASSWORD-NO-OLD

SET-PRINT-BY-FUNCTION

SQL-GENERATE-WHERE-LIKE

SQL-RESET-FAST-CURSOR

SQL-SET-FAST-CURSOR

STRIP-VALID-FILE-NAME

T Functions

TEXT-TO-HTML

TICKOVER

TRANSLATE-TEXT

TRANSLATE-TEXT-ADD

TRANSLATE-TEXT-GET

TRANSLATE-TEXT-INIT

TRANSLATE-TEXT-LIST

U Functions

UPDATE-JOB-LOGGING

UPDATE-SYSTEM-DATE-CCYYMMDD

UNPACK-CASES-AND-PIECES

UNPACK-INPUT-BYTE

V Functions

VERIFY-ACCESS

VERIFY-ACCESS-APBR

VERIFY-ACCESS-ARBR

VERIFY-ACCESS-BANK

VERIFY-ACCESS-FIELD

VERIFY-ACCESS-JOBCL

VERIFY-ACCESS-REP

VERIFY-ACCESS-TT

VERIFY-ACCESS-WH

VERIFY-PASSWORD

W Functions

WRITE-PRLINE-AFTER-1

WRITE-PRLINE-AFTER-2

WRITE-PRLINE-AFTER-3

WRITE-PRLINE-AFTER-4

WRITE-PRLINE-AFTER-5

WRITE-PRLINE-AFTER-6

WRITE-PRLINE-AFTER-7

WRITE-PRLINE-AFTER-8

WRITE-PRLINE-AFTER-9

WRITE-PRLINE-AFTER-PAGE

WRITE-PRLINE-AFTER-SKIP

WW

X Functions

X91-SCAN-COMPLETE

X91-SCAN-DIRECTORY

X91-SCAN-INITIALIZE

X91-SCAN-TERMINATE-EARLY


Functions by type

SYSPRO SDK

Function Reference

The following is a list of standard functions available from PROBEGIN.PRO by category.

Access control

FILTER-ACCESS

FILTER-ACCESS-APBR

FILTER-ACCESS-ARBR

FILTER-ACCESS-BANK

FILTER-ACCESS-CUS (e.net only)

FILTER-ACCESS-FIELD

FILTER-ACCESS-JOBCL

FILTER-ACCESS-REP

FILTER-ACCESS-TT

FILTER-ACCESS-WH

VERIFY-ACCESS

VERIFY-ACCESS-APBR

VERIFY-ACCESS-ARBR

VERIFY-ACCESS-BANK

VERIFY-ACCESS-FIELD

VERIFY-ACCESS-JOBCL

VERIFY-ACCESS-REP

VERIFY-ACCESS-TT

VERIFY-ACCESS-WH

VERIFY-PASSWORD

Custom form functions

CUSTOM-FORM-COPY

CUSTOM-FORM-COPY-TYPE

CUSTOM-FORM-DEL

CUSTOM-FORM-EDIT

CUSTOM-FORM-GET

CUSTOM-FORM-READ-ALL

CUSTOM-FORM-READ-ALL-DESC

CUSTOM-FORM-READ-CTL

CUSTOM-FORM-TEST

Client/Server functions

CHECK-FILE-EXISTS-ON-CLIENT

COPY-FILE-ON-SERVER

COPY-FILE-TO-CLIENT

COPY-FILE-TO-CLIENT-ASCII

COPY-FILE-TO-SERVER

COPY-FILE-TO-SERVER-ASCII

CREATE-DIRECTORY-ON-CLIENT

CREATE-DIRECTORY-ON-SERVER

DEL-FILE-ON-CLIENT

DEL-FILE-ON-SERVER

EXECUTE-COMMAND-ON-CLIENT

EXECUTE-COMMAND-ON-SERVER

GET-DIRECTORY-ON-CLIENT

GET-DIRECTORY-ON-SERVER

GET-STD-ENCORE-PATH

NULL-TASK

Database functions

BEGIN-TRANSACTION

COMMIT-TRANSACTION

GET-DATABASE-NAME

ROLLBACK-TRANSACTION

SQL-GENERATE-WHERE-LIKE

SQL-RESET-FAST-CURSOR

SQL-SET-FAST-CURSOR

Date functions

CALC-DATETIME-AGE

CALC-DATETIME-NEW-DATE

CALC-DATETIME-NEW-DATE-NUM

CALC-DAY-OF-WEEK

DATE-COMPARE

DATE-COMPARE-YMD

DATE-FROM-CYMD

DATE-NORM

DATE-TO-CYMD

DATE-YMD

EDIT-DATE-TO-USER-FORMAT

EDIT-DATE-TO-USER-FORMAT-CYMD

EDIT-DATE-YYYY-MM-DD

EDIT-FORMATTED-DATE

EDIT-REPORT-DATE

GET-COMPUTER-DATE-TIME

IS-DATE-VALID

IS-DATE-VALID-CYMD

IS-LEAP-YEAR

UPDATE-SYSTEM-DATE-CCYYMMDD

Editing and formatting functions

EDIT-DATE-TO-USER-FORMAT

EDIT-DATE-TO-USER-FORMAT-CYMD

EDIT-DATE-YYYY-MM-DD

EDIT-FORMATTED-DATE

EDIT-NO-LEADING-SPACES

EDIT-QUANTITY

EDIT-QUANTITY-LIST

EDIT-REPORT-DATE

FMT-POST

NULL-TERMINATE-STRING

NUMB-CHECK

UNPACK-CASES-AND-PIECES

UNPACK-INPUT-BYTE

Encryption functions

DECRYPT-CIPHER-TEXT

ENCRYPT-PLAIN-TEXT

File handling functions

BEGIN-TRANSACTION

BROWSE-ON-FILES

BUILD-BITMAP-NAME

BUILD-FILE-NAME

BUILD-PROGRAM-NAME

BUILD-SCREENSET-NAME

BUILD-STP-NAME

BUILD-TMPFIL

BUILD-TMPFIL-NO-PATH

BUILD-TMPFIL-NO-PATH-USER-EXT

BUILD-TMPFIL-USER-EXT

BUILD-USR-FILE-NAME

CHECK-FILE-EXISTS

CHECK-FILE-EXISTS-ON-CLIENT

CHECK-FILES-IN-USE

CHECK-SHARED-TABLE

CHECK-SHARED-TYPE

COMER

COMMIT-TRANSACTION

COPY-FILE-ON-SERVER

COPY-FILE-TO-CLIENT

COPY-FILE-TO-CLIENT-ASCII

COPY-FILE-TO-SERVER

COPY-FILE-TO-SERVER-ASCII

CREATE-DIRECTORY-ON-CLIENT

CREATE-DIRECTORY-ON-SERVER

DEL-FILE-ON-CLIENT

DEL-FILE-ON-SERVER

DELETE-WW-FILE-NAME

EXPAND-WW-FILE-NAME

EXECUTE-COMMAND-ON-CLIENT

EXECUTE-COMMAND-ON-SERVER

GENERATE-VALID-FILE-NAME

GET-COMPANY-LIST-ALL

GET-COMPANY-LIST-ALL-COMMA

GET-COMPANY-LIST-INV

GET-COMPANY-LIST-INV-COMMA

GET-CLIENT-IMPACT-INI

GET-DIRECTORY-ON-CLIENT

GET-DIRECTORY-ON-SERVER

GET-STD-ENCORE-PATH

GET-STD-SYSPRO-PATH

OUTPUT-DEBUG-LOG

QUOTE-VALID-FILE-NAME

READ-COMPANY-PATHS

ROLLBACK-TRANSACTION

SET-DIRECTORY-ON-CLIENT

SET-DIRECTORY-ON-SERVER

STRIP-VALID-FILE-NAME

X91-SCAN-COMPLETE

X91-SCAN-DIRECTORY

X91-SCAN-INITIALIZE

X91-SCAN-TERMINATE-EARLY

Locking functions

CLEAR-AP-PAY-LOCK

CLEAR-GL-ENT-LOCK

CLEAR-WIP-TRIAL-LOCK

DELETE-AP-PAY-LOCK

GET-AP-PAY-LOCK

GET-GL-ENT-LOCK-EXCLUSIVE

GET-GL-ENT-LOCK-SHARED

GET-WIP-TRIAL-LOCK-EXCLUSIVE

RESOURCE-LOCK-ADD

RESOURCE-LOCK-ADD-MSG

RESOURCE-LOCK-DELETE

RESOURCE-LOCK-TEST

RESOURCE-LOCK-TEST-MSG

Messages and Job logging functions

ADD-CHG-DEL-NOT-FOUND

ASK-BRW-MAINT-CONFIRM-MBOX

ASK-BRW-MAINT-RET-MBOX

COM-ERROR-MSG

CONTROL-ERROR

INVOKE-MESSAGE-BOX

INVOKE-MESSAGE-BOX-RESET

INVOKE-TASK-DIALOG

JOB-MESSAGE

JOB-MESSAGE-DETAIL

JOB-MESSAGE-IF-BLANK

JOB-MESSAGE-READ

JOB-MESSAGE-TRANSACT

LOOK-UP-ERROR

LOOKUP-MSG

MODULE-NOT-INSTALLED

OUTPUT-SYSTEM-JOB-LOG

UPDATE-JOB-LOGGING

Multimedia functions

MULTIMEDIA-DELETE-ALL

MULTIMEDIA-GET-PATH

MULTIMEDIA-PLAY

Password functions

ADD-PASSWORD-CTL

ASK-PASSWORD

CLEAR-FORCE-CHANGE-PASSWORD

DEL-PASSWORD

GET-PASSWORD-INFO

SET-FORCE-CHANGE-PASSWORD

SET-PASSWORD

SET-PASSWORD-NO-ASK

SET-PASSWORD-NO-OLD

VERIFY-PASSWORD

Printing functions

CLR-PRINT-BY-FUNCTION

GET-PRINT-BY-FUNCTION

PRINT-BOLD-OFF

PRINT-BOLD-ON

PRINT-CLOSE

PRINT-CLOSE-NO-PRINT

PRINT-HOF-UNDERLINE

PRINT-HORIZONTAL-LINE

PRINT-OPEN

REGISTER-MSG

RESET-TICKOVER

RETRIEVE-PRINT-BY-FUNCTION

SERV

SERVREQ

SET-PRINT-BY-FUNCTION

TICKOVER

WRITE-PRLINE-AFTER-1

WRITE-PRLINE-AFTER-2

WRITE-PRLINE-AFTER-3

WRITE-PRLINE-AFTER-4

WRITE-PRLINE-AFTER-5

WRITE-PRLINE-AFTER-6

WRITE-PRLINE-AFTER-7

WRITE-PRLINE-AFTER-8

WRITE-PRLINE-AFTER-9

WRITE-PRLINE-AFTER-PAGE

WRITE-PRLINE-AFTER-SKIP

Program functions

CALL-BO-ADD

CALL-BO-BUILD

CALL-BO-DELETE

CALL-BO-POST

CALL-BO-POST-RTGL

CALL-BO-QUERY

CALL-BO-UPDATE

CALL-PROGRAM

CALL-PROGRAM-NO-CANCEL

CANCEL-PROGRAM

CANNOT-RUN-STANDALONE

Screenset and user-interface functions

CALL-DS

INVOKE-MESSAGE-BOX

INVOKE-MESSAGE-BOX-RESET

INVOKE-TASK-DIALOG

QUIT-DS

QUIT-DS-ALWAYS

RESET-TICKOVER

SERV

SERVREQ

TICKOVER

Security

CHECK-IF-OPER-BELONGS-TO-GROUP

CHECK-MAINTENANCE

CHECK-MAINTENANCE-OTHER-PROG

CHECK-USER-STILL-VALID

GET-GROUPS-FOR-OPERATOR

MODULE-NOT-INSTALLED

REFRESH-SECURITY-SETTINGS

Text functions

CMS-READ-CONTACT-GUID-FRM-NAME

CMS-READ-CONTACT-NAME-FRM-GUID

CONVERT-ASCII-TO-HEX

CONVERT-GUID16-TO-GUID38

CONVERT-GUID38-TO-GUID16

CONVERT-HEX-TO-ASCII

CONVERT-LOWER-CASE

CONVERT-PATH-PRINT

CONVERT-UPPER-CASE

CONVERT-UPPER-LOWER

DECREMENT-LINE-X5

EXPAND-LINK-EXTRA

GENERATE-GUID

HTML-TO-TEXT

INCREMENT-LINE-X5

SQL-GENERATE-WHERE-LIKE

TEXT-TO-HTML

TRANSLATE-TEXT

TRANSLATE-TEXT-ADD

TRANSLATE-TEXT-GET

TRANSLATE-TEXT-INIT

TRANSLATE-TEXT-LIST

Miscellaneous

GET-ENVIRONMENT-STRING

GENERATE-GUID

OBJECT-COUNT-END

OBJECT-COUNT-START

PROCESS-WW-LOGIC-TAB

WW


ADD-CHG-DEL-NOT-FOUND

The ADD-CHG-DEL-NOT-FOUND function is used by a maintenance program to display a standardized message box when an operator attempts to delete an item that does not exist.

This function is part of the standards used when developing separate browse and maintenance functions.

Input parameters

BRW-MAINT-KEY

Key of item to be deleted (e.g. stock code or customer).

BRW-MAINT-DES

Description of the item to be deleted (e.g. stock code description or customer name).

Output parameters

none

Remarks

When developing browse and maintenance programs SYSPRO uses a number of standards to ensure consistency.

This function is provided to assist in providing a consistent user interface experience when attempting to delete an item. It should be used rather that hard-coding a custom message box or task dialog.

If you do not wish the key of the item to be shown in the confirmation message then move spaces to the field BRW-MAINT-KEY and just provide a description. Alternatively you can just move in the key of the item and leave the description blank. At least one of these fields must be provided and both can be provided if appropriate.

Sample code

* Display a message if unable to delete item

MOVE SPACES TO BRW-MAINT-FIELDS.

MOVE INVMST-STK TO BRW-MAINT-KEY. *> Stock code

MOVE INVMST-DESC TO BRW-MAINT-DES. *> Stock description

PERFORM ADD-CHG-DEL-NOT-FOUND.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

INVOKE-MESSAGE-BOX, INVOKE-TASK-DIALOG, ASK-BRW-MAINT-CONFIRM-MBOX, ASK-BRW-MAINT-RET-MBOX


ASK-BRW-MAINT-CONFIRM-MBOX

The ASK-BRW-MAINT-CONFIRM-MBOX function is used by a maintenance program to display a standardized message box when confirming if the operator wants to delete an item.

This function is part of the standards used when developing separate browse and maintenance functions.

Input parameters

BRW-MAINT-KEY

Key of item to be deleted (e.g. stock code or customer).

BRW-MAINT-DES

Description of the item to be deleted (e.g. stock code description or customer name).

BRW-MAINT-CON

Flag indicating whether you want to the confirmation message box to be shown.

Y - Yes

Output parameters

BRW-MAINT-DEL

Ok to delete item flag.

Y - Ok to delete item

Remarks

When developing browse and maintenance programs SYSPRO uses a number of standards to ensure consistency.

This function is provided to assist in providing a consistent user interface experience when attempting to delete an item. It should be used rather that hard-coding a custom message box or task dialog.

If you do not wish the key of the item to be shown in the confirmation message then move spaces to the field BRW-MAINT-KEY and just provide a description.

Sample code

* Confirm if ok to delete a stock code

MOVE SPACES TO BRW-MAINT-FIELDS.

MOVE "Y" TO BRW-MAINT-CON. *> Ask confirm flag (Y-Yes)

MOVE INVMST-STK TO BRW-MAINT-KEY. *> Stock code

MOVE INVMST-DESC TO BRW-MAINT-DES. *> Stock description

PERFORM ASK-BRW-MAINT-CONFIRM-MBOX.

IF BRW-MAINT-DEL = "Y"

PERFORM DELETE-ITEM

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

ADD-CHG-DEL-NOT-FOUND, ASK-BRW-MAINT-RET-MBOX, INVOKE-MESSAGE-BOX, INVOKE-TASK-DIALOG


ASK-BRW-MAINT-RET-MBOX

The ASK-BRW-MAINT-RET-MBOX function is used by a maintenance program to display a standardized message box when confirming if the operator add an item using the current values.

This function is part of the standards used when developing separate browse and maintenance functions.

Input parameters

none

Output parameters

BRW-MAINT-RET

Ok to add item flag using current values

Y - Add item retaining previous values

N - Initialize to default values

Remarks

When developing browse and maintenance programs SYSPRO uses a number of standards to ensure consistency.

This function is provided to assist in providing a consistent user interface experience when attempting to add an item. It should be used rather that hard-coding a custom message box or task dialog.

Sample code

* Confirm if should add item using current values

PERFORM ASK-BRW-MAINT-RET-MBOX.

IF BRW-MAINT-RET = "Y"

PERFORM FILL-REC-LAYOUT-FROM-PREV-ITEM

ELSE

PERFORM FILL-REC-LAYOUT-WITH-DEFAULT-VALUES

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

ADD-CHG-DEL-NOT-FOUND, ASK-BRW-MAINT-CONFIRM-MBOX, INVOKE-MESSAGE-BOX, INVOKE-TASK-DIALOG


ASK-PASSWORD

The ASK-PASSWORD function is used to request a password and to verify that the entered password matches an existing password.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being verified.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

LINK-PASS-KEY

This is the key of the item being protected.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

Output parameters

LINK-PASS-OK

This flag indicates whether the operator entered a valid password.

Spaces – Yes

E – password expired (operator passwords)

N – Password was not verified

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The ASK-PASSWORD function allows the developer to prompt the operator for a password. The system will automatically verify the entered password and return a flag indicating whether the password was entered successfully. There is no need to provide any user-interface as this is entirely handled by the function.

Sample code

* Ask the password for the S/Order changing prices function

* See IMPPSS.IMP for the password type

MOVE SPACES TO LINK-PASS.

MOVE "-SOR03" TO LINK-PASS-TYP. *> See IMPPSS.IMP for the codes

PERFORM ASK-PASSWORD.

IF LINK-PASS-OK = SPACES

MOVE SPACES TO LINK-PASS

GO TO PASSWORD-ENTERED-CORRECTLY

ELSE

MOVE SPACES TO LINK-PASS

GO TO ABORT-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-OLD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD


ADD-PASSWORD-CTL

The ADD-PASSWORD-CTL function is used to initialise your own password control record. This only has to be done once per password type.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password control being defined.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required. Note that for the operator file this will be blank.

Output parameters

none

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The ADD-PASSWORD-CTL function must be issued once to define your password type. Once this has been issued you can set, verify and delete passwords.

Sample code

* Add password control for 'USRDOC' type

MOVE "USRDOC" TO LINK-PASS-TYP. *> My 'USRDOC' passwords

MOVE COMPID TO LINK-PASS-CMP. *> Company specific

PERFORM ADD-PASSWORD-CTL.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-OLD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, DEL-PASSWORD


BEGIN-TRANSACTION

The BEGIN-TRANSACTION function is used to start a logical business transaction. This is primarily used in SQL Server based systems to issue the BEGIN TRANSACTION SQL statement.

You should define a transaction description before calling this function. In the event of a transaction failure this description will be shown to the operator and can be used to identify any problems.

In addition the job logging will be updated to indicate that a transaction is in progress and the transaction description is held in case of failure.

Use COMMIT-TRANSACTION to end the logical transaction and release any resources held by the transaction.

Input parameters

LINK-SQL-TRAN-TEXT

This is a 40 character transaction description.

COMER-TO-ENDJOB

A flag indicating whether a COMER failure during a transaction should branch to ENDJOB. The default is that you must test the NOT STAT-OK setting yourself.

E – Branch to ENDJOB on failure

Output parameters

LINK-SQL-TRANSACT

This is an indicator that a transaction is in progress. You can read this value but you must not change it.

Y - Yes

Remarks

Transaction Processing is a concept that ensures that all data added, changed or deleted as part of a logical process is either completed successfully or completely undone – as if it had never happened.

This is best explained with an example

Suppose we wish to debit a ledger code with $100 and credit another with $100. This is our logical business transaction as we must not have one without the other. In this case a transaction will be started. The program will credit the first Ledger code and then debit the second Ledger code. Upon completion the transaction will be finalised (committed).

However in the real world there are several things that could go wrong during this process. Imagine that the first item is debited but before the second item is credited one of the following problems occur. This is how it will be handled.

Software problem

In the event of a software problem, for example the second account is not valid, then the program can display a message indicating the cause of the problem, the description of the transaction in progress and that it will be rolled back. The COMER function will issue a ROLLBACK-TRANSACTION function which ensures that the initial debit is undone. The operator should either retry the transaction or attempt to fix the problem (perhaps selecting the correct Ledger code) and then retry.

Client PC or Network problem

In the case of a Client PC failure, Windows failure or a network problem SQL Server will detect the break in the connection to the server on which SQL Server is running and that a transaction is in progress. This will cause an automatic rollback to be issued by SQL Server. When the operator next logs back into SYSPRO they can retry the transaction that failed.

SQL Server failure or hardware failure on the server

In this case when SQL Server itself fails or the server that it is running on fails - then when the server is next booted and SQL Server is loaded the SQL Server system will detect that a system failure occurred. If no damage was done to the database structure by the crash then a rollback of the uncompleted transaction will be issued. When the operator next logs back into SYSPRO they can retry the transaction that failed.

If a hard disk crash occurred and the transaction log was recovered (it is highly recommended to store the transaction log on a separate disk drive) then the last backup can be restored to a new disk and the transaction log rolled-forward so that all changes up to the crash are applied. SQL Server will then rollback any uncompleted transactions.

From the above description you can see that Transaction Processing ensures that the data integrity of a transaction is guaranteed.

To assist in determining the causes of transaction failures it is highly recommended that the programmer uses a reasonably descriptive transaction description so that in the event of a failure the operator is made aware of what was in process and the Job Logging will also show the processing that was being performed when the failure occurred.

It is important to remember the following when using transactions

  • Whilst a transaction is in process all data accesses cause locks to be applied so that other processes do not interfere with the transaction. This includes reading data when using the READ-LOCK and READ-WAIT functions.

  • Due to the above resources being used and held during a transaction it is recommended to keep the transaction as short as possible. You should not start a transaction and allow the operator to respond as they could take a long time – during which – the resources are locked.

  • During a transaction any access to data locked by another transaction will block the current transaction. The system will retry indefinitely and appears to hang during this process. This is another good reason to keep transactions a small and a quick as possible.

  • It is important that during a transaction all data access uses the COMER function after every access. This will verify the integrity of the data access and automatically issue the ROLLBACK-TRANSACTION function in the event of failure.

  • Also note that during a transaction any failure detected by a COMER function will not branch to the ENDJOB routine. You must detect the NOT STAT-OK condition and branch as required. To force the COMER function to branch to ENDJOB you can move E to COMER-TO-ENDJOB

It is important to only have a single transaction active at any one time. You must not use nested transactions. This is particularly important when calling multiple programs during an open transaction. Your program can check the value in LINK-SQL-TRANSACT for a Y to determine whether a transaction is in progress.

Whilst Transaction Processing is primarily designed for SQL Server based companies the same logic should be used for C-ISAM based companies. In this event a system failure cannot rollback partially modified data however the operator is still made aware of any problems and the Job Logging can be used to see failed transactions.

Also note that when using the generic C-ISAM functions to lock a record the COMMIT-TRANSACTION function will release all locks held for the program.

Sample code

* Start a transaction

MOVE "Debit A $100 and Credit B $100" TO LINK-SQL-TRAN-TEXT.

MOVE "E" TO COMER-TO-ENDJOB.

PERFORM BEGIN-TRANSACTION.

* Credit A with $100

MOVE COMPID TO GENMST-CMP.

MOVE "A" TO GENMST-ACC.

PERFORM GENMST-READ.

PERFORM COMER.

ADD 100 TO GENMST-DR. *> Add to Period to date Debits $100

ADD 100 TO GENMST-CBAL. *> Update balance

PERFORM GENMST-REWRITE.

PERFORM COMER

* Credit B with $100

MOVE COMPID TO GENMST-CMP.

MOVE "B" TO GENMST-ACC.

PERFORM GENMST-READ.

PERFORM COMER.

ADD 100 TO GENMST-CR. *> Add to Prd to date Credits

SUBTRACT 100 FROM GENMST-CBAL. *> Update balance

PERFORM GENMST-REWRITE.

PERFORM COMER

* Done

PERFORM COMMIT-TRANSACTION.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Transaction Processing, COMMIT-TRANSACTION, ROLLBACK-TRANSACTION, COMER, ENDJOB


BROWSE-ON-FILES

The BROWSE-ON-FILES function is used to allow an operator to browse and select Files and or Folders. This function works in both a mapped drive and client/server environments. In a client/server environment you can select whether the File/Folder resides on the Client or the Server.

This function is commonly called directly from a screenset using the S-FILE-BRW function.

Input parameters

S-FR-PAR

File browsing - This is the default file name, including path, to be used for the browse. If there is no path then the base directory will be used as the default folder. Note that when using the File Open function that the file name shown in the browse will default to spaces.

Folder browsing - If you are using the Folder browse option then this field should be an existing folder with or without a trailing slash. If you leave this field blank then the Folder browse will default to the base folder.

S-FR-EXT

An indicator specifying the type of browse required

O – Open. The file must exist when returning from the browse

S – Save As. A warning will be displayed if the file already exists

B - Browse. Any file may be selected and no validation is performed on the file being selected.

F - Folder. This provides a Folder browse. The folder must exist when returning from the browse.

S-BRW1

A list of up to 10 x 3 character file extension that will be shown in the Files of Type selection box. For example 'BMPJPGGIF'. The first entry will be the default. An entry of '* ' means all files and will automatically be added if not supplied.

Remember files are case sensitive on Unix servers.

S-BRW2

An indicator specifying whether the file is on the Client or Server on a client/server environment. This has no effect on a mapped drive system.

S - Server (default)

C – Client

S-BRW3

This field allows you to specify a 30 character dialog box title. A default title will be provided if you leave this field blank.

Output parameters

S-TO-PAR

The selected file name. If a spacey file or folder name is returned it will be quoted.

If blank then the operator cancelled the browse.

Remarks

This function is typically called from a screenset using the S-FILE-BRW function but can be called from a SYSPRO program as required.

Note that spacey file names generally must be enclosed in quotes to be used for file handling functions. See QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME for routines to add or remove quotes to/from spacey file names. The browse will return spacey File/Folder names quoted. However it is not necessary to supply quotes for the default File/Folder name passed.

It is highly recommended to supply a default extension as this makes it much easier for the operator to find the file they required. For example when looking for an Import file you could look for files with a txt extension. This is especially useful when navigating through various directories so that spurious files are not shown.

The user-interface shown when selecting File or Folder browsing is very similar to the standard Windows 2000/XP style common dialog control. Note however that it is not exactly the same. This browse dialog does allow browsing on both Client and Server systems - even Unix servers where applicable.

This proprietary file/folder browse currently has the following limits:

  • Only the first 3000 matching files per folder are shown

  • Only the first 200 sub-folders for the current folder are shown

  • No attempt is made to show the associated icon with each file shown

  • The Look in selection box shows more basic information (without icons) than the standard Windows Look in selection box

  • The context sensitive 'Right Click' to Copy, Delete, Rename, edit Properties etc has been disabled to prevent operators making changes. See the operator/role activities.

Sample code

MOVE "c:\temp\report.txt" TO D-S-FR-PAR. *> Default name

MOVE "O" TO D-S-FR-EXT. *> Default to Open

MOVE "txt" TO D-S-BRW1. *> Look for '*.txt'

MOVE "S" TO D-S-BRW2. *> Files on the server

MOVE "Select a txt File" TO D-S-BRW3. *> Dialog box heading

PERFORM BROWSE-ON-FILES.

IF D-S-TO-PAR NOT = SPACES

MOVE D-S-TO-PAR TO FILE-NAME-SELECTED

ELSE

GO TO CANCELLED-FROM-BROWSE.

Requirements

Version: Included in Encore 5.0 and later. The ability to use the File Browse and Folder Browse (functions B and F) is only available in SYSPRO 6.0 Issue 006 and onwards.

Copybooks: standard

See also

spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-FILE-BRW


BUILD-BITMAP-NAME

The BUILD-BITMAP-NAME function is used to build the full path to a bitmap. This will build a file name in the multi-media directory.

Input parameters

WW-FILE-NAME

The name of a file (usually bitmap).

Output parameters

WW-FILE-NAME

The built file name in the multi-media directory.

Remarks

The multi-media directory is defined in the System Setup program.

Note that spacey file names generally must be enclosed in quotes to be used for file handling functions. See QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME for routines to add or remove quotes to/from spacey file names.

Sample code

MOVE "INVOICE.BMP" TO WW-FILE-NAME.

PERFORM BUILD-BITMAP-NAME.

MOVE WW-FILE-NAME TO FULL-PATH-OF-BITMAP.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME


BUILD-FILE-NAME

The BUILD-FILE-NAME function is used to build the full path to a data file. This is commonly used by each data files' standard build name function but can be called by a user program when required. Note that on a company configured as a SQL Server based company the file name built has a specific SQL Server file name format.

Input parameters

WW-FILE-CODE

A 6 character file code identifying the file.

WW-COMPID

Usually set to spaces to indicate that the current company id is to be used as a prefix for the data file name. Alternatively move in the specific company id required. This must be A-Z or 0-9

WW-PATH

Usually set to spaces to indicate the default path for the company or the specific path defined in the file exceptions in the Company Setup program. Alternatively can be one of the following:

1-9 | a hard-coded path number defined in the System Setup program
S | build the name in the snapshot directory
s | always build the file name as a sequential file – forces a disk file name for SQL Server based systems
I | always build the file name as C-ISAM – forces a disk file name for SQL Server based systems
D | always build the file name in BASE\DD directory even if a SQL Server based company.

Output parameters

WW-FILE-NAME

The built file name.

Remarks

This function is usually called by each files build file name routine. However the flags in WW-COMPID and WW-PATH can be useful to override the default settings.

On a Windows environment data files have an extension of .DAT – this will be added automatically. On Unix environments data files do not have an extension.

Note that building a data file name using the BUILD-FILE-NAME function will build a special file name on a SQL Server based company. See SQL Server file name format for more details. It is important that the program is compiled with the CALLFH"IMPFHX" compiler directive for this special file name to be used correctly.

Note that spacey directories will be quoted to allow Net Express to open the file. To use Win32 API calls in the built file name you will need to use STRIP-VALID-FILE-NAME.

Sample code

MOVE "ARSMST" TO WW-FILE-CODE.

MOVE "A" TO WW-COMPID.

PERFORM BUILD-FILE-NAME.

MOVE WW-FILE-NAME TO FULL-PATH-OF-ARSMST-COMPANY-A.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

spacey file names, STRIP-VALID-FILE-NAME, CHECK-SHARED-TABLE


BUILD-PROGRAM-NAME

The BUILD-PROGRAM-NAME function is used to build the full path to a program. This function is used by the CALL-PROGRAM function and does not generally need to be used by a user program. However there are some parameters that can be used to build file names, other than program names, in the program directory.

Input parameters

WW-PROG-NAME

A 6 character program/file name.

WW-PROG-DIR

A flag indicating whether the standard or a custom program directory is used and whether the standard program extensions are tried or a user specified extension will be used.

P | the program directory is tried with the program name extension of .gnt and if not found then .int. If the program name is found in CUSTOM.IMP the custom program directory will be used else the standard program directory will be used.
p | the file specified has a user supplied extension defined in WW-PROG-EXT. If the file name is found in CUSTOM.IMP the custom program directory will be used else the standard program directory will be used.
S | the file name is built with the standard program directory and the user supplied extension in WW-PROG-EXT.
C | the file name is built with the custom program directory and the user supplied extension in WW-PROG-EXT.

WW-PROG-EXT

The user supplied extension for parameters p, S, and C above.

Output parameters

WW-RET-PROG

The built program/file name.

WW-FILE-EXISTS

Flag indicating whether the program/file exists

'N' – No

Remarks

This function is usually called by the CALL-PROGRAM function however there are some parameters to make it more flexible for other purposes such as locating files and programs in the standard and custom program directories.

This is useful to find files such as IMPPRG.IMP, IMPFIL.IMP and IMPMOD.IMP.

Sample code

MOVE "IMPPRG" TO WW-PROG-NAME.

MOVE "IMP" TO WW-PROG-EXT.

MOVE "S" TO WW-PROG-DIR.

PERFORM BUILD-PROGRAM-NAME.

MOVE WW-RET-PROG TO FULL-PATH-OF-IMPPRG-IMP.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

CALL-PROGRAM, IMPPRG.IMP, IMPFIL.IMP, IMPMOD.IMP


BUILD-SCREENSET-NAME

The BUILD-SCREENSET-NAME function is used internally by the CALL-DS function when initially calling a screenset. It should not generally be used by a user program.

Input parameters

SCREENSET-NAME

A 6 character screenset name.

Output parameters

SCREENSET-FULL

A full path to the screenset including the drive, folder, name and extension. In a client/server environment this is the path to the screenset on the server.

SCREENSET-NAME-EXT

Name of the screenset and extension excluding the drive and path.

SCREENSET-SIZE

The size of the screenset on disk in bytes. Zero indicates that the screenset does not exist. In a client/server environment this is the size of the screenset on the server.

SCREENSET-CUS

A flag indicating whether the screenset is in the custom screenset directory.

'C' – Screenset in Customized directory

Remarks

This is an internal command and should rarely be needed by a user program.

This function can be used to build a screenset name to find out whether a screenset exists.

The flag indicating standard or custom is derived from the contents of CUSTOM.IMP.

Sample code

MOVE "INVPEN" TO SCREENSET-NAME.

PERFORM BUILD-SCREENSET-NAME.

MOVE SCREENSET-FULL TO SCREENSET-NAME-ON-SERVER.

MOVE SCREENSET-SIZE TO SCREENSET-SIZE-ON-SERVER.

MOVE SCREENSET-NAME-EXT TO SCREENSET-PLUS-EXT.

MOVE SCREENSET-CUS TO STANDARD-OR-CUSTOM-FLAG.

IF SCREENSET-SIZE > ZERO

GO TO SCREENSET-EXISTS-ROUTINE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

CALL-DS, CUSTOM.IMP


BUILD-STP-NAME

The BUILD-STP-NAME function is used to build the full path to a file name in the Advanced Planning and Scheduling (APS) data directory defined in the System Setup program.

Input parameters

WW-FILE-NAME

The name of a file.

Output parameters

WW-FILE-NAME

The built file name in the APS data directory.

Remarks

The APS data directory is defined in the System Setup program.

This directory is used to pass files to/from an APS system.

Sample code

MOVE "EXPORT.DAT" TO WW-FILE-NAME.

PERFORM BUILD-STP-NAME.

MOVE WW-FILE-NAME TO FULL-PATH-OF-EXPORT-DAT.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME


BUILD-TEMP-TABLE-NAME

The BUILD-TEMP-TABLE-NAME function is used to build a temporary table name for use with optimized SQL Server statements.

Input parameters

none

Output parameters

TMPFIL

A temporary table name that can be used in optimized SQL Server statements.

Remarks

This function is used to build a temporary table name for use in subsequent optimized SQL Server statements.

The table name generated is of the form #Syspro_T1234001 which is designed to be unique across SYSPRO companies running on the same working folder.

The '#' at the beginning of the table name indicates to SQL Server that the table should be created in the system database tempdb. When an application disconnects from SQL Server any tables created in tempdb by that application will be automatically removed.

See the topic Creating Temporary Tables for more information on the actual coding to generate SQL Server temporary tables and some important information about SQL Server collation.

Sample code

PERFORM BUILD-TEMP-TABLE-NAME.

MOVE TMPFIL TO TEMPORARY-TABLE-NAME. *> defined in working-storage

Requirements

Version: Included in SYSPRO 6.0 issue 008 and later

Copybooks: standard

See also

Creating Temporary Tables, temporary ISAM files


BUILD-TMPFIL

The BUILD-TMPFIL function is used to build a temporary file name that will be unique across all users sharing the same SYSPRO system. On a Client/Server system this is a server file name.

Input parameters

none

Output parameters

TMPFIL

A full path to a temporary file name.

Remarks

This function uses the TEMP environment variable (on the server in a client/server environment) to locate the directory to be used. If this is not defined then the IMPTMP= entry in the server's IMPACT.INI file is used instead.

On a Windows based system the file name will automatically have an extension of .DAT whilst on a Unix server no extension will be generated.

The basic file name consists of a prefix (_T) followed by a 7 digit number. This 7 digit number is designed to be unique across a SYSPRO system.

For example on a Windows based system with a TEMP environment variable set to C:\Temp a file name generated could be:

C:\Temp\_T1234001.DAT

This function will ensure that the file does not already exist. If a file name already exists with the generated name then it will automatically generate another file name.

If you need to supply your own file extension (for example for an XML file) or alternatively want just the file name so you can add your own path then you can use one of the other temporary file name routines such as BUILD-TMPFIL-USER-EXT, BUILD-TMPFIL-NO-PATH, BUILD-TMPFIL-NO-PATH-USER-EXT

Sample code

PERFORM BUILD-TMPFIL.

OPEN OUTPUT TMP.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

Temporary files, BUILD-TMPFIL-USER-EXT, BUILD-TMPFIL-NO-PATH, BUILD-TMPFIL-NO-PATH-USER-EXT, IMPACT.INI


BUILD-TMPFIL-NO-PATH

The BUILD-TMPFIL-NO-PATH function is used to build a temporary file name with the standard file extension without any path. The file name will be unique across all users sharing the same SYSPRO system.

Input parameters

none

Output parameters

TMPFIL

A temporary file name.

Remarks

This function is typically used where your program requires to generate a temporary file name in a user-specified directory. This function allows you to build the temporary file name leaving it up to you to prefix with a path when required.

On a Windows based system the file name will automatically have an extension of .DAT whilst on a Unix server no extension will be generated.

The basic file name consists of a prefix (_T) followed by a 7 digit number. This 7 digit number is designed to be unique across a SYSPRO system.

For example on a Windows based system the file name generated could be:

_T1234001.DAT

Other temporary file name routines include BUILD-TMPFIL, BUILD-TMPFIL-USER-EXT, BUILD-TMPFIL-NO-PATH-USER-EXT.

Sample code

PERFORM BUILD-TMPFIL-NO-PATH.

MOVE SPACES TO FULL-PATH.

STRING FOLDER-NAME DELIMITED BY " "

TMPFIL DELIMITED BY " "

INTO FULL-PATH.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

temporary file, BUILD-TMPFIL, BUILD-TMPFIL-USER-EXT, BUILD-TMPFIL-NO-PATH-USER-EXT


BUILD-TMPFIL-NO-PATH-USER-EXT

The BUILD-TMPFIL-NO-PATH-USER-EXT function is used to build a temporary file name with your own required file extension without any path. The file name will be unique across all users sharing the same SYSPRO system.

Input parameters

WW-FILE-EXT

A 3 character file extension. For example 'xml'.

Output parameters

TMPFIL

A temporary file name.

Remarks

This function is typically used where your program requires to generate a temporary file name in a user-specified directory. This function allows you to build the temporary file name with your own extension leaving it up to you to prefix with a path when required.

The basic file name consists of a prefix (_T) followed by a 7 digit number. This 7 digit number is designed to be unique across a SYSPRO system.

For example on a Windows based system with a user-defined extension of 'xml' the file name generated could be:

_T1234001.xml

Remember that on a Unix Server the file names are case sensitive.

Other temporary file name routines include BUILD-TMPFIL, BUILD-TMPFIL-USER-EXT, BUILD-TMPFIL-NO-PATH.

Sample code

MOVE "xml" TO WW-FILE-EXT.

PERFORM BUILD-TMPFIL-NO-PATH-USER-EXT.

MOVE SPACES TO FULL-PATH.

STRING FOLDER-NAME DELIMITED BY " "

TMPFIL DELIMITED BY " "

INTO FULL-PATH.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

temporary file, BUILD-TMPFIL, BUILD-TMPFIL-USER-EXT, BUILD-TMPFIL-NO-PATH


BUILD-TMPFIL-USER-EXT

The BUILD-TMPFIL-USER-EXT function is used to build a temporary file name with your own required file extension. The file name will be unique across all users sharing the same SYSPRO system. On a Client/Server system this is a server file name.

Input parameters

WW-FILE-EXT

A 3 character file extension. For example 'xml'.

Output parameters

TMPFIL

A full path to a temporary file name.

Remarks

This function uses the TEMP environment variable (on the server in a client/server environment) to locate the directory to be used. If this is not defined then the IMPTMP= entry in the server's IMPACT.INI file is used instead.

The basic file name consists of a prefix (_T) followed by a 7 digit number. This 7 digit number is designed to be unique across a SYSPRO system.

For example on a Windows based system with a TEMP environment variable set to C:\Temp a file name generated with a user-defined extension of 'xml' could be:

C:\Temp\_T1234001.xml

This function will ensure that the file does not already exist. If a file name already exists with the generated name then it will automatically generate another file name.

Remember that on a Unix Server the file names are case sensitive.

Other temporary file name routines include BUILD-TMPFIL, BUILD-TMPFIL-NO-PATH, BUILD-TMPFIL-NO-PATH-USER-EXT.

Sample code

MOVE "xml" TO WW-FILE-EXT.

PERFORM BUILD-TMPFIL-USER-EXT.

OPEN OUTPUT TMP.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

temporary file, BUILD-TMPFIL, BUILD-TMPFIL-NO-PATH, BUILD-TMPFIL-NO-PATH-USER-EXT


BUILD-USR-FILE-NAME

The BUILD-USR-FILE-NAME function is used to build the full path to a data file. This is supplied for user programs to construct a non-standard file name.

Input parameters

WW-USR-FILE-CODE

A 6 character file code identifying the file.

WW-USR-COID

Usually set to spaces to indicate that the current company id is to be used as a prefix for the data file name. Alternatively move in the specific company id required. This must be A-Z or 0-9. Alternatively move in LOW-VALUES to indicate that this file name must not have a company id.

WW-USR-PATH

Usually set to spaces to indicate the default path for the company. Alternatively can be one of the following:

1-9 | a hard-coded path number defined in the System Setup program
S | build the name in the snapshot directory
W | build the name in the working directory.

Output parameters

WW-FILE-NAME

The built file name.

Remarks

This function is provided to allow user programs to build non-standard file names.

Note that spacey directories will be quoted to allow Net Express to open the file. To use Win32 API calls in the built file name you will need to use STRIP-VALID-FILE-NAME.

Sample code

MOVE "CUSTOM" TO WW-FILE-CODE.

MOVE "W" TO WW-COMPID.

PERFORM BUILD-FILE-NAME.

MOVE WW-FILE-NAME TO FULL-PATH-CUSTOM-IN-WORK-DIR.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

spacey directories, STRIP-VALID-FILE-NAME


CALC-DATETIME-AGE

The CALC-DATETIME-AGE function is used to calculate the numbers of days and time between two date-time fields. Date-time fields consist of both a date and time.

Input parameters

WW-DATETIME1-CYMD

First date in CCYYMMDD format

WW-DATETIME1-HMSF

First time in HHMMSSFF format. Where:

HH - 2 digit hours (00-23)

MM - 2 digit minutes (00-59)

SS - 2 digit seconds (00-59)

FF - 2 digit fractions of a second (00-99)

WW-DATETIME2-CYMD

Second date in CCYYMMDD format

WW-DATETIME2-HMSF

Second time in HHMMSSFF format. Where:

HH - 2 digit hours (00-23)

MM - 2 digit minutes (00-59)

SS - 2 digit seconds (00-59)

FF - 2 digit fractions of a second (00-99)

Output parameters

WW-DATETIME-FIRST

Flag indicating which date-time field is first chronologically.

0 - both dates and times are identical

1 - date-time 1 is first

2 - date-time 2 is first

WW-DAYSTIME-DAYS

Number of whole days between the two date-time values.

Zero upwards

WW-DAYSTIME-HMSF

Number of hours, minutes, seconds and fractions of a second between the two date-time values excluding the number of whole days.

Remarks

This function is designed to be used where you have two values that are a date and a time and you wish to determine the number of days, hours, minutes, seconds and fractions of a second (1/100th) between them.

For example the job logging file has a program start date-time and an end date-time and you may wish to calculate the duration of the program. This function is ideal for this purpose.

Similarly the Contact Managament System Activity file has a start date-time and an activity end date-time. This function is used to calculate the activity duration.

There are functions to allow you to calculate a new date-time given an existing date-time and a value. These functions are CALC-DATETIME-NEW-DATE and CALC-DATETIME-NEW-DATE-NUM.

Sample code

*> Determine whether a CMS Activity is due now,

*> in the future or in the past

PERFORM GET-COMPUTER-DATE-TIME.

MOVE COMPUTER-CCYYMMDD TO WW-DATETIME1-CYMD.

MOVE COMPUTER-TIME TO WW-DATETIME1-HMSF.

MOVE CRMACT-ST-DATE TO WW-DATETIME2-CYMD.

MOVE CRMACT-ST-DATE TO WW-DATETIME2-HMSF.

PERFORM CALC-DATETIME-AGE.

EVALUATE WW-DATETIME-FIRST

WHEN ZERO

MOVE "Now" TO DUE-MSG

WHEN 1

MOVE "Future" TO DUE-MSG

WHEN 2

MOVE "Past" TO DUE-MSG

END-EVALUATE.

MOVE WW-DAYSTIME-DAYS TO NUMBER-OF-DAYS.

Requirements

Version: Included in SYSPRO 6.0 Issue 010 SP2 Port 35 (November 2008).

Copybooks: standard

See also

Date ageing functions, CALC-DATETIME-NEW-DATE, CALC-DATETIME-NEW-DATE-NUM


CALC-DATETIME-NEW-DATE

The CALC-DATETIME-NEW-DATE function is used to calculate a new date-time value given an existing date-time and a number of days and a number of hours, minutes seconds and fractions of a second.

Input parameters

WW-DATETIME1-CYMD

First date in CCYYMMDD format

WW-DATETIME1-HMSF

First time in HHMMSSFF format. Where:

HH - 2 digit hours (00-23)

MM - 2 digit minutes (00-59)

SS - 2 digit seconds (00-59)

FF - 2 digit fractions of a second (00-99)

WW-DAYSTIME-DAYS

Number of whole days to increment or decrement the passed date-time.

Zero upwards

WW-DAYSTIME-HMSF

Number of hours, minutes, seconds and fractions of a second to increment or decrement the passed date-time. This is in HHMMSSFF format where:

HH - 2 digit hours (00-23)

MM - 2 digit minutes (00-59)

SS - 2 digit seconds (00-59)

FF - 2 digit fractions of a second (00-99)

WW-DAYSTIME-ADD

Add or subtract the values from the passed date-time.

A - Add WW-DAYSTIME-DAYS and WW-DAYSTIME-HMSF to date-time to generate a future date-time.

S - Subtract WW-DAYSTIME-DAYS and WW-DAYSTIME-HMSF from date-time to generate an older date-time.

Output parameters

WW-DATETIME2-CYMD

Result date in CCYYMMDD format

WW-DATETIME2-HMSF

Result time in HHMMSSFF format. Where:

HH - 2 digit hours (00-23)

MM - 2 digit minutes (00-59)

SS - 2 digit seconds (00-59)

FF - 2 digit fractions of a second (00-99)

Remarks

This function is designed to be used where you have an initial date-time value and wish to calculate a date-time value in the future or past.

The Contact Managament System Activity file has a start date-time and an activity follow up date-time. When the start date-time is changed you can use this function to manipulate the follow up date-time to keep an appropriate follow up. This can be done by using both the CALC-DATETIME-AGE and CALC-DATETIME-NEW-DATE functions

There is a function to allow you to calculate a new date-time given a number of weeks, days, hours or minutes into the future or past. This function is called CALC-DATETIME-NEW-DATE-NUM.

Sample code

*> Calculate a date-time exactly 4 hours and 30 minutes

*> in the future. Takes account of new days etc.

PERFORM GET-COMPUTER-DATE-TIME.

MOVE COMPUTER-CCYYMMDD TO WW-DATETIME1-CYMD.

MOVE COMPUTER-TIME TO WW-DATETIME1-HMSF.

MOVE ZERO TO WW-DAYSTIME-DAYS.

MOVE "04300000" TO WW-DAYSTIME-HMSF. *> 4hrs 30m

MOVE "A" TO WW-DATETIME-ADD. *> Calc future date-time

PERFORM CALC-DATETIME-NEW-DATE.

MOVE WW-DATETIME2-CYMD TO FUTURE-DATE.

MOVE WW-DATETIME2-HMSF TO FUTURE-TIME.

Requirements

Version: Included in SYSPRO 6.0 Issue 010 SP2 Port 35 (November 2008).

Copybooks: standard

See also

Date ageing functions, CALC-DATETIME-AGE, CALC-DATETIME-NEW-DATE-NUM


CALC-DATETIME-NEW-DATE-NUM

The CALC-DATETIME-NEW-DATE-NUM function is used to calculate a new date-time value given a number of weeks, days, hours or minutes into the future or past.

Input parameters

WW-DATETIME1-CYMD

First date in CCYYMMDD format

WW-DATETIME1-HMSF

First time in HHMMSSFF format. Where:

HH - 2 digit hours (00-23)

MM - 2 digit minutes (00-59)

SS - 2 digit seconds (00-59)

FF - 2 digit fractions of a second (00-99)

WW-DAYSTIME-WDHM

Flag indicating the value that we are passing:

W - Weeks

D - Days

H - Hours

M - Minutes

WW-DAYSTIME-NUM

Numeric value containing number of weeks, days, hours or minutes.

WW-DAYSTIME-ADD

Add or subtract the value from the passed date-time.

A - Add WW-DAYSTIME-NUM to date-time to generate a future date-time.

S - Subtract WW-DAYSTIME-NUM from date-time to generate an older date-time.

Output parameters

WW-DATETIME2-CYMD

Result date in CCYYMMDD format

WW-DATETIME2-HMSF

Result time in HHMMSSFF format. Where:

HH - 2 digit hours (00-23)

MM - 2 digit minutes (00-59)

SS - 2 digit seconds (00-59)

FF - 2 digit fractions of a second (00-99)

Remarks

This function is designed to be used where you have an initial date-time value and wish to calculate a date-time value in the future or past.

The value passed can be either a number of weeks, number or days, number of hours or number of minutes.

The best example of this function is when using Contact Management and wish to set a reminder for a meeting or appointment. The choices include values such as 'Remind me in':

5 minutes

10 minutes

15 minutes

30 minutes

1 hour

2 hours

1 day

2 days

1 week

etc

Note that this function differs from CALC-DATETIME-NEW-DATE in that this function allows you to pass large numbers. e.g. you can pass 90 minutes or 72 hours etc.

There are related functions for manipulating date-time values called CALC-DATETIME-NEW-DATE and CALC-DATETIME-AGE.

Sample code

*> Calculate a date-time 90 minutes before

*> an activity start date

PERFORM GET-COMPUTER-DATE-TIME.

MOVE CRMACT-ST-DATE TO WW-DATETIME1-CYMD.

MOVE CRMACT-ST-TIME TO WW-DATETIME1-HMSF.

MOVE "M" TO WW-DATETIME-WDHM. *> Minutes

MOVE 90 TO WW-DATETIME-NUM. *> 90

MOVE "S" TO WW-DATETIME-ADD. *> 90 minutes before

PERFORM CALC-DATETIME-NEW-DATE-NUM.

MOVE WW-DATETIME2-CYMD TO REMIND-DATE.

MOVE WW-DATETIME2-HMSF TO REMIND-TIME.

Requirements

Version: Included in SYSPRO 6.0 Issue 010 SP2 Port 35 (November 2008).

Copybooks: standard

See also

Date ageing functions, CALC-DATETIME-AGE, CALC-DATETIME-NEW-DATE


CALC-DAY-OF-WEEK

The CALC-DAY-OF-WEEK function is used to calculate the day of the week from a date stored in the SYSPRO standard date format. The returned value is a number from 0 through 6 where 0 is Sunday.

Input parameters

DATE-NORMAL

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

Output parameters

WW-DATE-DOW

A single digit numeric field indicating the day of week.

0 – Sunday

1 – Monday

2 – Tuesday

3 – Wednesday

4 – Thursday

5 – Friday

6 – Saturday

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

Dates in this format can be in the range

1st Jan 1950 through 31st Dec 2049

This function must only be used with valid dates in the above date range.

To convert dates in CCYYMMDD to the SYSPRO standard date format use DATE-TO-CYMD

Sample code

MOVE D-ASK-DATE TO DATE-NORMAL.

PERFORM CALC-DAY-OF-WEEK.

EVALUATE WW-DATE-DOW

WHEN 0 MOVE "Sunday " TO DAY-OF-WEEK

WHEN 1 MOVE "Monday " TO DAY-OF-WEEK

WHEN 2 MOVE "Tuesday " TO DAY-OF-WEEK

WHEN 3 MOVE "Wednesday" TO DAY-OF-WEEK

WHEN 4 MOVE "Thursday " TO DAY-OF-WEEK

WHEN 5 MOVE "Friday " TO DAY-OF-WEEK

WHEN 6 MOVE "Saturday " TO DAY-OF-WEEK

END-EVALUATE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-TO-CYMD, Date ageing functions


CALL-BO-ADD

The CALL-BO-ADD function is used to call an Add business object from your Net Express program. You must build two XML strings to be passed to the business object. After using the CALL-BO-ADD function you will generally parse the returned XML string to extract any return values.

In addition the business object may return an exception. You should test for this exception and take appropriate action.

See the topic Calling Business Objects Overview for more information.

Input parameters

WW-PROG-NAME

The 6 character business object name.

COMMN2-XMLIN

This object contains the XML string to be passed to the business object. This contains details of the item to be added. You must use the various standard functions to build this XML object. See Remarks below.

COMMN2-PARAMETERS

This object contains an XmlParameter XML string to be passed to the business object. This contains information about how the business object should process the XML input string - for example whether warnings should be ignored. You must use the various standard functions to build this XML object. See Remarks below.

Output parameters

LINK-COM-RETURN

This is a status field indicating whether an exception occurred.

Zero - the call to the business object was successful

Non-zero - an exception was returned - LINK-EXTRA contains the exception message

LINK-EXTRA

If an exception was returned (LINK-COM-RETURN was non-zero) then this field contains the exception message in the current language. Often you will display this in a message box - the function INVOKE-MESSAGE-BOX can be used for this.

COMMN2-XMLOUT

This object contains the XML string returned from the business object if no exception was returned. You should use one of the XML parsing functions to extract information from the XML string. You must not access this object unless a zero was returned in LINK-COM-RETURN.

Remarks

The CALL-BO-ADD function is used to call Add business objects allowing you to add items to the SYSPRO database. This typically follows the following steps:

Your program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMMN2-XMLOUT TO NULL. It is best practise to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

Use various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build both the XmlIn and XmlParameter XML strings that will be used as the input to the Add business object. See the Calling Business Objects Overview for information about these functions. The valid XML input is described in the e.net object model reference against the Setup.Add method.

The program calls the Add business object using the CALL-BO-ADD function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. The function INVOKE-MESSAGE-BOX can be used to display the exception message.

If the business object returned successfully (zero in LINK-COM-RETURN) then your program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be queried looking for the value of a single XML element

2. The returned XML can be parsed allowing you to traverse the XML tree finding any XML element values

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

See the topic Calling Business Objects Overview for more information.

Sample source code

The program SDKCB3.CBL is provided as part of the Software Development Kit and demonstrates use of the CALL-BO-ADD function.

Calling Other Types of Business Objects

You can call business objects that are not Add objects by using the following functions: CALL-BO-QUERY, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST.

Licensing considerations

See the topic Calling Business Objects Overview for more information about licensing considerations.

Sample code

See the source code SDKCB3.CBL for sample code showing calling the CALL-BO-ADD function.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later.

Copybooks: standard. Also COMPAR.LNK, ARRAY.WRK, COMPAR.PRO and ARRAY.PRO.

See also

Calling Business Objects Overview, Setup.Add, CALL-BO-QUERY, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST, INVOKE-MESSAGE-BOX


CALL-BO-BUILD

The CALL-BO-BUILD function is used to call a Build business object from your Net Express program. You must build an XML string to be passed to the business object. After using the CALL-BO-BUILD function you will generally parse the returned XML string to extract any return values.

In addition the business object may return an exception. You should test for this exception and take appropriate action.

See the topic Calling Business Objects Overview for more information.

Input parameters

WW-PROG-NAME

The 6 character business object name.

COMBL2-XMLIN

This object contains the XML string to be passed to the business object. This contains details of the item to be built. You must use the various standard functions to build this XML object. See Remarks below.

Output parameters

LINK-COM-RETURN

This is a status field indicating whether an exception occurred.

Zero - the call to the business object was successful

Non-zero - an exception was returned - LINK-EXTRA contains the exception message

LINK-EXTRA

If an exception was returned (LINK-COM-RETURN was non-zero) then this field contains the exception message in the current language. Often you will display this in a message box - the function INVOKE-MESSAGE-BOX can be used for this.

COMBL2-XMLOUT

This object contains the XML string returned from the business object if no exception was returned. You should use one of the XML parsing functions to extract information from the XML string. You must not access this object unless a zero was returned in LINK-COM-RETURN.

Remarks

The CALL-BO-BUILD function is used to call Build business objects allowing you to return information about the item passed. This is typically used to return information that can subsequently be used to post a transaction using the CALL-BO-POST function. For example when building information for a sales order you can pass the customer and the build sales order business object will return default values about the customer. This typically follows the following steps:

Your program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMBL2-XMLOUT TO NULL. It is best practise to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

Use various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build the XmlIn XML string that will be used as the input to the Build business object. See the Calling Business Objects Overview for information about these functions. The valid XML input is described in the e.net object model reference against the Transaction.Build method.

The program calls the Build business object using the CALL-BO-BUILD function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. The function INVOKE-MESSAGE-BOX can be used to display the exception message.

If the business object returned successfully (zero in LINK-COM-RETURN) then your program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be queried looking for the value of a single XML element

2. The returned XML can be parsed allowing you to traverse the XML tree finding any XML element values

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

See the topic Calling Business Objects Overview for more information.

Sample source code

The program SDKCB4.CBL is provided as part of the Software Development Kit and demonstrates use of the CALL-BO-BUILD function.

Calling Other Types of Business Objects

You can call business objects that are not Build objects by using the following functions: CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-POST.

Licensing considerations

See the topic Calling Business Objects Overview for more information about licensing considerations.

Sample code

See the source code SDKCB4.CBL for sample code showing calling the CALL-BO-BUILD function. A code fragment from this program is shown below.

*

** Create the XmlIn string to call ARSQRY. For example:

** <build>

** <parameters>

** <customer>CUS001</customer>

** </parameters>

** </build>

*

** First create the root element - adds standard XML prolog

** This creates an object called 'ARRAY-OBJECT'

MOVE "Build" TO XML-ROOT-NAME.

PERFORM CREATE-XML-HEADER.

MOVE "<Parameters>" TO ARRAY-DATA.

MOVE ZEROS TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

MOVE "Customer" TO XML-TAG-NAME.

MOVE D-CUSTOMER TO XML-TAG-VALUE.

PERFORM OUTPUT-ELEMENT.

MOVE "</Parameters>" TO ARRAY-DATA.

MOVE ZEROS TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

MOVE "</Build>" TO ARRAY-DATA.

MOVE ZEROS TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

*

** Complete the XmlIn string

PERFORM ARRAY-FINAL-CREATE.

SET COMBL2-XMLIN TO ARRAY-OBJECT.

*

** Build up the linkage and call the business object

MOVE SPACES TO LINK-EXTRA.

MOVE "SORRSH" TO WW-PROG-NAME.

PERFORM CALL-BO-BUILD.

*

** Check for any exceptions - error message is in LINK-EXTRA

** We will use a simple Message box for the exception message

IF LINK-COM-RETURN <> ZEROS

MOVE LINK-COM-RETURN TO EDIT-EXCEPTION-NUM

MOVE SPACES TO LINK-MSG-HDG

STRING "Exception Raised (" DELIMITED BY SIZE

EDIT-EXCEPTION DELIMITED BY SIZE

")" DELIMITED BY SIZE

INTO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Exception}" TO D-NAME

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO BUILD-END.

*

** Parse the XML - if invalid then goes to endjob with exception

** If valid this returns the number of nodes

SET COMPAR-OBJECT TO COMBL2-XMLOUT.

MOVE "N" TO COMPAR-TO-ENDJOB.

PERFORM COMPAR-PARSE-XML.

MOVE "Y" TO COMPAR-TO-ENDJOB.

IF LINK-COM-RETURN <> ZERO

MOVE "XML Parsing Message" TO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Xml Parse Error}" TO D-NAME

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO BUILD-END.

*

** Retrieve the single element '<arsmst:name>'

MOVE "arsmst:name" TO COMPAR-QUERY.

PERFORM COMPAR-SELECT-SINGLE-NODE.

MOVE COMPAR-SINGLE-VALUE TO D-NAME.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later.

Copybooks: standard. Also COMPAR.LNK, ARRAY.WRK, COMPAR.PRO and ARRAY.PRO.

See also

Calling Business Objects Overview, Transaction.Build, CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-POST, INVOKE-MESSAGE-BOX


CALL-BO-DELETE

The CALL-BO-DELETE function is used to call a Delete business object from your Net Express program. You must build two XML strings to be passed to the business object. After using the CALL-BO-DELETE function you will generally parse the returned XML string to extract any return values.

In addition the business object may return an exception. You should test for this exception and take appropriate action.

See the topic Calling Business Objects Overview for more information.

Input parameters

WW-PROG-NAME

The 6 character business object name.

COMMN2-XMLIN

This object contains the XML string to be passed to the business object. This contains the key of the item to be deleted. You must use the various standard functions to build this XML object. See Remarks below.

COMMN2-PARAMETERS

This object contains an XmlParameter XML string to be passed to the business object. This contains information about how the business object should process the XML input string - for example whether warnings should be ignored. You must use the various standard functions to build this XML object. See Remarks below.

Output parameters

LINK-COM-RETURN

This is a status field indicating whether an exception occurred.

Zero - the call to the business object was successful

Non-zero - an exception was returned - LINK-EXTRA contains the exception message

LINK-EXTRA

If an exception was returned (LINK-COM-RETURN was non-zero) then this field contains the exception message in the current language. Often you will display this in a message box - the function INVOKE-MESSAGE-BOX can be used for this.

COMMN2-XMLOUT

This object contains the XML string returned from the business object if no exception was returned. You should use one of the XML parsing functions to extract information from the XML string. You must not access this object unless a zero was returned in LINK-COM-RETURN.

Remarks

The CALL-BO-DELETE function is used to call Delete business objects allowing you to delete items from the SYSPRO database. This typically follows the following steps:

Your program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMMN2-XMLOUT TO NULL. It is best practise to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

Use various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build both the XmlIn and XmlParameter XML strings that will be used as the input to the Update business object. Note that XmlIn contains the key of the item to be deleted. See the Calling Business Objects Overview for information about these functions. The valid XML input is described in the e.net object model reference against the Setup.Delete method.

The program calls the Delete business object using the CALL-BO-DELETE function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. The function INVOKE-MESSAGE-BOX can be used to display the exception message.

If the business object returned successfully (zero in LINK-COM-RETURN) then your program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be queried looking for the value of a single XML element

2. The returned XML can be parsed allowing you to traverse the XML tree finding any XML element values

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

See the topic Calling Business Objects Overview for more information.

Sample source code

The program SDKCB3.CBL is provided as part of the Software Development Kit and demonstrates use of the CALL-BO-DELETE function.

Calling Other Types of Business Objects

You can call business objects that are not Update objects by using the following functions: CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-BUILD, CALL-BO-POST.

Licensing considerations

See the topic Calling Business Objects Overview for more information about licensing considerations.

Sample code

See the source code SDKCB3.CBL for sample code showing calling the CALL-BO-DELETE function.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later.

Copybooks: standard. Also COMPAR.LNK, ARRAY.WRK, COMPAR.PRO and ARRAY.PRO.

See also

Calling Business Objects Overview, Setup.Delete, CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-BUILD, CALL-BO-POST, INVOKE-MESSAGE-BOX


CALL-BO-POST

The CALL-BO-POST function is used to call a Post business object from your Net Express program. You must build two XML strings to be passed to the business object. After using the CALL-BO-POST function you will generally parse the returned XML string to extract any return values.

In addition the business object may return an exception. You should test for this exception and take appropriate action.

See the topic Calling Business Objects Overview for more information.

Input parameters

WW-PROG-NAME

The 6 character business object name.

COMPS2-XMLIN

This object contains the XML string to be passed to the business object. This contains details of the item to be posted. You must use the various standard functions to build this XML object. See Remarks below.

COMPS2-PARAMETERS

This object contains an XmlParameter XML string to be passed to the business object. This contains information about how the business object should process the XML input string - for example the default order status value of newly added orders. You must use the various standard functions to build this XML object. See Remarks below.

Output parameters

LINK-COM-RETURN

This is a status field indicating whether an exception occurred.

Zero - the call to the business object was successful

Non-zero - an exception was returned - LINK-EXTRA contains the exception message

LINK-EXTRA

If an exception was returned (LINK-COM-RETURN was non-zero) then this field contains the exception message in the current language. Often you will display this in a message box - the function INVOKE-MESSAGE-BOX can be used for this.

COMPS2-XMLOUT

This object contains the XML string returned from the business object if no exception was returned. You should use one of the XML parsing functions to extract information from the XML string. You must not access this object unless a zero was returned in LINK-COM-RETURN.

Remarks

The CALL-BO-POST function is used to call Post business objects allowing you to post transactions to the SYSPRO database. This typically follows the following steps:

Your program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMPS2-XMLOUT TO NULL. It is best practise to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

Use various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build both the XmlIn and XmlParameter XML strings that will be used as the input to the Post business object. See the Calling Business Objects Overview for information about these functions. The valid XML input is described in the e.net object model reference against the Transaction.Post method.

The program calls the Post business object using the CALL-BO-POST function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. The function INVOKE-MESSAGE-BOX can be used to display the exception message.

If the business object returned successfully (zero in LINK-COM-RETURN) then your program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be queried looking for the value of a single XML element

2. The returned XML can be parsed allowing you to traverse the XML tree finding any XML element values

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

See the topic Calling Business Objects Overview for more information.

Sample source code

The program SDKCB5.CBL is provided as part of the Software Development Kit and demonstrates use of the CALL-BO-POST function.

Calling Other Types of Business Objects

You can call business objects that are not Add objects by using the following functions: CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD.

Licensing considerations

See the topic Calling Business Objects Overview for more information about licensing considerations.

Sample code

See the source code SDKCB5.CBL for sample code showing calling the CALL-BO-POST function. A code fragment from this program is shown below.

PERFORM SETUP-XML-PARAMETER.

PERFORM SETUP-XML-IN.

*

** Build up the linkage and call the business object

MOVE SPACES TO LINK-EXTRA.

MOVE "SORTOI" TO WW-PROG-NAME.

PERFORM CALL-BO-POST

*

** Check for any exceptions - error message is in LINK-EXTRA

** We will use a simple Message box for the exception message

IF LINK-COM-RETURN <> ZEROS

MOVE LINK-COM-RETURN TO EDIT-EXCEPTION-NUM

MOVE SPACES TO LINK-MSG-HDG

STRING "Exception Raised (" DELIMITED BY SIZE

EDIT-EXCEPTION DELIMITED BY SIZE

")" DELIMITED BY SIZE

INTO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Exception}" TO D-RET-CUSTOMER-PO-NUM

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO POST-END.

*

** Parse the XML - if invalid then goes to endjob with exception

** If valid this returns the number of nodes

SET COMPAR-OBJECT TO COMPS2-XMLOUT.

MOVE "N" TO COMPAR-TO-ENDJOB.

PERFORM COMPAR-PARSE-XML.

MOVE "Y" TO COMPAR-TO-ENDJOB.

IF LINK-COM-RETURN <> ZERO

MOVE "XML Parsing Message" TO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Xml Parse Error}" TO D-RET-CUSTOMER-PO-NUM

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO POST-END.

*

** Select the single node 'ErrorDescription'

MOVE "errordescription" TO COMPAR-QUERY.

PERFORM COMPAR-SELECT-SINGLE-NODE.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later.

Copybooks: standard. Also COMPAR.LNK, ARRAY.WRK, COMPAR.PRO and ARRAY.PRO.

See also

Calling Business Objects Overview, Transaction.Post, CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, INVOKE-MESSAGE-BOX


CALL-BO-POST-RTGL

The CALL-BO-POST-RTGL function is used to call a Post business object from your Net Express program.

Note - this function is virtually identical to the CALL-BO-POST function except that when invoking business objects that can post to the Real-Time GL (RTGL) the logic will post to the RTGL (when configured appropriately). By default SYSPRO business objects that 'can' post to the RTGL do not do so unless this function is performed. This was done for historical reasons.

Examples of business objects that can post to the Real-Time GL include: APSTIN, ARSTIN, ARSTPY, ASSTAD, CSHTWD, INVTBF, PORTGR, SORTIC, WIPTMI.

The rest of this documentation is identical to the CALL-BO-POST function.

You must build two XML strings to be passed to the business object. After using the CALL-BO-POST function you will generally parse the returned XML string to extract any return values.

In addition the business object may return an exception. You should test for this exception and take appropriate action.

See the topic Calling Business Objects Overview for more information.

Input parameters

WW-PROG-NAME

The 6 character business object name.

COMPS2-XMLIN

This object contains the XML string to be passed to the business object. This contains details of the item to be posted. You must use the various standard functions to build this XML object. See Remarks below.

COMPS2-PARAMETERS

This object contains an XmlParameter XML string to be passed to the business object. This contains information about how the business object should process the XML input string - for example the default order status value of newly added orders. You must use the various standard functions to build this XML object. See Remarks below.

Output parameters

LINK-COM-RETURN

This is a status field indicating whether an exception occurred.

Zero - the call to the business object was successful

Non-zero - an exception was returned - LINK-EXTRA contains the exception message

LINK-EXTRA

If an exception was returned (LINK-COM-RETURN was non-zero) then this field contains the exception message in the current language. Often you will display this in a message box - the function INVOKE-MESSAGE-BOX can be used for this.

COMPS2-XMLOUT

This object contains the XML string returned from the business object if no exception was returned. You should use one of the XML parsing functions to extract information from the XML string. You must not access this object unless a zero was returned in LINK-COM-RETURN.

Remarks

The CALL-BO-POST-RTGL function is used to call Post business objects allowing you to post transactions to the SYSPRO database. This typically follows the following steps:

Your program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMPS2-XMLOUT TO NULL. It is best practise to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

Use various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build both the XmlIn and XmlParameter XML strings that will be used as the input to the Post business object. See the Calling Business Objects Overview for information about these functions. The valid XML input is described in the e.net object model reference against the Transaction.Post method.

The program calls the Post business object using the CALL-BO-POST function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. The function INVOKE-MESSAGE-BOX can be used to display the exception message.

If the business object returned successfully (zero in LINK-COM-RETURN) then your program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be queried looking for the value of a single XML element

2. The returned XML can be parsed allowing you to traverse the XML tree finding any XML element values

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

See the topic Calling Business Objects Overview for more information.

Sample source code

The program SDKCB5.CBL is provided as part of the Software Development Kit and demonstrates use of the CALL-BO-POST function. Note that this is not the CALL-BO-POST-RTGL function.

Calling Other Types of Business Objects

You can call business objects that are not Add objects by using the following functions: CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD.

Licensing considerations

See the topic Calling Business Objects Overview for more information about licensing considerations.

Sample code

See the source code SDKCB5.CBL for sample code showing calling the CALL-BO-POST function. A code fragment from this program is shown below.

PERFORM SETUP-XML-PARAMETER.

PERFORM SETUP-XML-IN.

*

** Build up the linkage and call the business object

MOVE SPACES TO LINK-EXTRA.

MOVE "SORTOI" TO WW-PROG-NAME.

PERFORM CALL-BO-POST

*

** Check for any exceptions - error message is in LINK-EXTRA

** We will use a simple Message box for the exception message

IF LINK-COM-RETURN <> ZEROS

MOVE LINK-COM-RETURN TO EDIT-EXCEPTION-NUM

MOVE SPACES TO LINK-MSG-HDG

STRING "Exception Raised (" DELIMITED BY SIZE

EDIT-EXCEPTION DELIMITED BY SIZE

")" DELIMITED BY SIZE

INTO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Exception}" TO D-RET-CUSTOMER-PO-NUM

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO POST-END.

*

** Parse the XML - if invalid then goes to endjob with exception

** If valid this returns the number of nodes

SET COMPAR-OBJECT TO COMPS2-XMLOUT.

MOVE "N" TO COMPAR-TO-ENDJOB.

PERFORM COMPAR-PARSE-XML.

MOVE "Y" TO COMPAR-TO-ENDJOB.

IF LINK-COM-RETURN <> ZERO

MOVE "XML Parsing Message" TO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Xml Parse Error}" TO D-RET-CUSTOMER-PO-NUM

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO POST-END.

*

** Select the single node 'ErrorDescription'

MOVE "errordescription" TO COMPAR-QUERY.

PERFORM COMPAR-SELECT-SINGLE-NODE.

Requirements

Version: Included in SYSPRO 6.1 Port 34 and later. However you must also verify that the specific business object you are using has been updated to support this function.

Copybooks: standard. Also COMPAR.LNK, ARRAY.WRK, COMPAR.PRO and ARRAY.PRO.

See also

Calling Business Objects Overview, Transaction.Post, CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST, INVOKE-MESSAGE-BOX


CALL-BO-QUERY

The CALL-BO-QUERY function is used to call a Query business object from your Net Express program. You must build an XML string to be passed to the business object. After using the CALL-BO-QUERY function you will generally parse the returned XML string to extract any return values.

In addition the business object may return an exception. You should test for this exception and take appropriate action.

See the topic Calling Business Objects Overview for more information.

Input parameters

WW-PROG-NAME

The 6 character business object name.

COMQRY-XMLIN

This object contains the XML string to be passed to the business object. You must use the various standard functions to build this XML object. See Remarks below.

Output parameters

LINK-COM-RETURN

This is a status field indicating whether an exception occurred.

Zero - the call to the business object was successful

Non-zero - an exception was returned - LINK-EXTRA contains the exception message

LINK-EXTRA

If an exception was returned (LINK-COM-RETURN was non-zero) then this field contains the exception message in the current language. Often you will display this in a message box - the function INVOKE-MESSAGE-BOX can be used for this.

COMQR2-XMLOUT

This object contains the XML string returned from the business object if no exception was returned. You should use one of the XML parsing functions to extract information from the XML string. You must not access this object unless a zero was returned in LINK-COM-RETURN.

Remarks

The CALL-BO-QUERY function is used to call Query business objects. This typically follows the following steps:

Your program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMQR2-XMLOUT TO NULL. It is best practise to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

Use various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build an XML string that will be used as the input to the Query business object. See the Calling Business Objects Overview for information about these functions. The valid XML input is described in the e.net object model reference against the Query.Query method.

The program calls the Query business object using the CALL-BO-QUERY function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. The function INVOKE-MESSAGE-BOX can be used to display the exception message.

If the business object returned successfully (zero in LINK-COM-RETURN) then your program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be queried looking for the value of a single XML element

2. The returned XML can be parsed allowing you to traverse the XML tree finding any XML element values

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

See the topic Calling Business Objects Overview for more information.

Sample source code

The programs SDKCB1.CBL and SDKCB2.CBL are provided as part of the Software Development Kit and demonstrates use of the CALL-BO-QUERY function.

Calling Other Types of Business Objects

You can call business objects that are not Query objects by using the following functions: CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST.

Licensing considerations

See the topic Calling Business Objects Overview for more information about licensing considerations.

Sample code

See the READ-ROUTINE described in the source code SDKCB1.CBL for sample code showing calling the CALL-BO-QUERY function. A code fragment from this program is shown below.

*

** Create the XmlIn string to call ARSQRY. For example:

** <query>

** <key>

** <customer>CUS001</customer>

** </key>

** </query>

*

** First create the root element - adds standard XML prolog

** This creates an object called 'ARRAY-OBJECT'

MOVE "query" TO XML-ROOT-NAME.

PERFORM CREATE-XML-HEADER.

*

** Create the rest of the XmlIn string

MOVE "<key>" TO ARRAY-DATA.

MOVE 5 TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

MOVE "customer" TO XML-TAG-NAME.

MOVE D-CUSTOMER TO XML-TAG-VALUE.

PERFORM OUTPUT-ELEMENT.

MOVE "</key>" TO ARRAY-DATA.

MOVE 6 TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

MOVE "</query>" TO ARRAY-DATA.

MOVE 8 TO ARRAY-LENGTH.

PERFORM ARRAY-CREATE.

*

** Complete the XmlIn string

PERFORM ARRAY-FINAL-CREATE.

*

** Build up the linkage and call the business object

MOVE SPACES TO LINK-EXTRA.

SET COMQR2-XMLIN TO ARRAY-OBJECT.

MOVE "ARSQRY" TO WW-PROG-NAME.

PERFORM CALL-BO-QUERY.

*

** Check for any exceptions - error message is in LINK-EXTRA

** We will use a simple Message box for the exception message

IF LINK-COM-RETURN <> ZEROS

MOVE LINK-COM-RETURN TO EDIT-EXCEPTION-NUM

MOVE SPACES TO LINK-MSG-HDG

STRING "Exception Raised (" DELIMITED BY SIZE

EDIT-EXCEPTION DELIMITED BY SIZE

")" DELIMITED BY SIZE

INTO LINK-MSG-HDG

PERFORM INVOKE-MESSAGE-BOX

MOVE "{Exception}" TO D-NAME

MOVE ZEROS TO LINK-COM-RETURN

MOVE SPACES TO LINK-EXTRA

GO TO READ-END.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later.

Copybooks: standard. Also COMPAR.LNK, ARRAY.WRK, COMPAR.PRO and ARRAY.PRO.

See also

Calling Business Objects Overview, Query.Query, CALL-BO-ADD, CALL-BO-UPDATE, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST, INVOKE-MESSAGE-BOX


CALL-BO-UPDATE

The CALL-BO-UPDATE function is used to call an Update business object from your Net Express program. You must build two XML strings to be passed to the business object. After using the CALL-BO-UPDATE function you will generally parse the returned XML string to extract any return values.

In addition the business object may return an exception. You should test for this exception and take appropriate action.

See the topic Calling Business Objects Overview for more information.

Input parameters

WW-PROG-NAME

The 6 character business object name.

COMMN2-XMLIN

This object contains the XML string to be passed to the business object. This contains details of the item to be updated - only fields that are to be updated need to be defined. You must use the various standard functions to build this XML object. See Remarks below.

COMMN2-PARAMETERS

This object contains an XmlParameter XML string to be passed to the business object. This contains information about how the business object should process the XML input string - for example whether warnings should be ignored. You must use the various standard functions to build this XML object. See Remarks below.

Output parameters

LINK-COM-RETURN

This is a status field indicating whether an exception occurred.

Zero - the call to the business object was successful

Non-zero - an exception was returned - LINK-EXTRA contains the exception message

LINK-EXTRA

If an exception was returned (LINK-COM-RETURN was non-zero) then this field contains the exception message in the current language. Often you will display this in a message box - the function INVOKE-MESSAGE-BOX can be used for this.

COMMN2-XMLOUT

This object contains the XML string returned from the business object if no exception was returned. You should use one of the XML parsing functions to extract information from the XML string. You must not access this object unless a zero was returned in LINK-COM-RETURN.

Remarks

The CALL-BO-UPDATE function is used to call Update business objects allowing you to update items to the SYSPRO database. This typically follows the following steps:

Your program must perform COMPAR-INITIALIZE-OBJECTS to initialize the objects used by the XML parser. In addition the output XML object should be initialized using SET COMMN2-XMLOUT TO NULL. It is best practise to perform these functions before any other processing occurs - even before PROBEGIN.PRO.

Use various SYSPRO XML functions (CREATE-XML-HEADER, ARRAY-CREATE, OUTPUT-ELEMENT and ARRAY-CREATE-FINAL) to build both the XmlIn and XmlParameter XML strings that will be used as the input to the Update business object. Note that only fields that are to be updated need to be described in the XmlIn string - all other fields will be left unchanged. See the Calling Business Objects Overview for information about these functions. The valid XML input is described in the e.net object model reference against the Setup.Update method.

The program calls the Update business object using the CALL-BO-UPDATE function.

After the business object has been called the program must check if any exceptions were raised. This is done by testing the field LINK-COM-RETURN for non-zeros. If an exception was raised the exception description is found in LINK-EXTRA. The function INVOKE-MESSAGE-BOX can be used to display the exception message.

If the business object returned successfully (zero in LINK-COM-RETURN) then your program can parse the returned XML string. This can be done in one of two ways:

1. The returned XML can be queried looking for the value of a single XML element

2. The returned XML can be parsed allowing you to traverse the XML tree finding any XML element values

When the program has finished parsing the returned XML it should perform the COMPAR-FINALIZE-OBJECTS function to release any objects that are in use by the XML parser. In addition you should perform COMPAR-CANCEL to cancel the XML parser from memory.

See the topic Calling Business Objects Overview for more information.

Sample source code

The program SDKCB3.CBL is provided as part of the Software Development Kit and demonstrates use of the CALL-BO-UPDATE function.

Calling Other Types of Business Objects

You can call business objects that are not Update objects by using the following functions: CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST.

Licensing considerations

See the topic Calling Business Objects Overview for more information about licensing considerations.

Sample code

See the source code SDKCB3.CBL for sample code showing calling the CALL-BO-UPDATE function.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later.

Copybooks: standard. Also COMPAR.LNK, ARRAY.WRK, COMPAR.PRO and ARRAY.PRO.

See also

Calling Business Objects Overview, Setup.Update, CALL-BO-QUERY, CALL-BO-ADD, CALL-BO-DELETE, CALL-BO-BUILD, CALL-BO-POST, INVOKE-MESSAGE-BOX


CALL-DS

The CALL-DS function is used to call a screenset. Before being called the first time the data block and control block must be initialised and the name of the screenset must be passed. The CALL-DS function is usually placed inside an event handling loop to allow the screenset to direct the action of the program. The field D-S-FR-MSG is usually used by the screenset to indicate the function to be actioned.

Input parameters

DS-CONTROL-BLOCK

The dialog system control block must be initialised the first time.

D-DATA-BLOCK

The data block must be initialised the first time. After this the individual data block fields will be filled in by the program passing values to the screenset.

SCREENSET-NAME

This field must be passed the first time. It must be a 6 character name (no extension or path)

DSG-CONTROL

The first time this must be initialised with value DSG-PUSH-SET. After the first call this field will have the value DSG-CONTINUE and should not be changed.

Output parameters

DS-CONTROL-BLOCK

Various fields are updated and must not be changed by the user program.

D-DATA-BLOCK

The screenset passes back messages and values into the data block. These should be used as required.

Remarks

This routine is the heart of the user-interface. It provides the mechanism of communicating with the screenset.

Generally the CALL-DS function will be placed inside a simple event loop (see the sample code below) responding to events from the screenset. Once the event has been handled the CALL-DS function is called again to wait for the next event.

Various standard dialog functions are parsed and handled before the CALL-DS function returns. This is how many standard functions are handled by the SYSPRO system.

The CALL-DS function handles the interface to the screenset on a mapped drive or client/server configuration. In this case the CALL-DS function calls the client system.

When the program has finished with it's user-interface it must QUIT-DS to release the system resources and set the focus back to the previous screenset.

If you want to animate the screenset see the article Animating a Screenset.

Sample code

INITIALIZE DS-CONTROL-BLOCK.

INITIALIZE D-DATA-BLOCK.

MOVE "CUSTOM" TO SCREENSET-NAME.

MOVE DSG-PUSH-SET TO DSG-CONTROL.

MAIN-DS-LOOP.

PERFORM CALL-DS.

EVALUATE D-S-FR-MSG

WHEN "print" PERFORM PRINT-FUNCTION

WHEN "add" PERFORM ADD-FUNCTION

WHEN "update" PERFORM UPDATE-FUNCTION

WHEN "delete" PERFORM DELETE-FUNCTION

END-EVALUATE.

GO TO MAIN-DS-LOOP.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

dialog functions by name, dialog functions by type, QUIT-DS


CALL-PROGRAM

The CALL-PROGRAM function is used to call another SYSPRO program or custom Net Express program developed in a SYSPRO style. A 6 character program name is passed to this function which will build and locate the full path to the program. The standard linkage fields are passed to the program and returned on completion.

Often one or more parameters are passed in a field called LINK-EXTRA. It is possible to pass any length string in addition to the standard linkage.

Input parameters

WW-PROG-NAME

The 6 character program name to be called.

LINK-EXTRA

Parameters can be passed in LINK-EXTRA as well as in LNK2.

Output parameters

LINK-EXTRA

Optionally the called program may pass a value back into this field.

LNK2

Optionally the called program may pass a value back into this user defined field.

Remarks

This is the recommended method of calling any SYSPRO program or any user developed custom program written in a SYSPRO style (i.e. using PROBEGIN.PRO and LINK.WRK).

You cannot call a program already in use by this run-unit. An error message will be displayed and the function will return.

When using LINK-EXTRA to pass a value to another program you should move in the value to LINK-EXTRA immediately before the CALL-PROGRAM function. The called program must retrieve/save this value and immediately move spaces to LINK-EXTRA.

When retrieving a parameter in LINK-EXTRA passed from a called program your program must save the value in LINK-EXTRA immediately after the CALL-PROGRAM function and then move spaces to LINK-EXTRA.

Passing more text than allowed by LINK-EXTRA (600 bytes) requires the use of LNK2. To pass text in LNK2 requires you to defined LNK2 as the data to be passed, then use the CALL-PROGRAM function as normal. The called program must have the same definition defined in its LINK2 parameter. It is a good idea (but not mandatory) to pass a value to confirm this convention in LINK-EXTRA.

If the system administrator has logged out the current user then the CALL-PROGRAM function will fail.

After the CALL-PROGRAM function has completed the called program will be cancelled from memory. You can use the CALL-PROGRAM-NO-CANCEL function to leave the called program in memory to make subsequent calls faster. Care must be taken to ensure that the working storage and file usage is carefully designed as the program will be left in the previous state when it exits. You should manually cancel the program from memory when you have finished with it to return the resources to the operating system.

Note that when calling programs in a COM environment that they will not be cancelled from memory. See the CALL-PROGRAM-NO-CANCEL and CANCEL-PROGRAM functions.

If the program name is defined in CUSTOM.IMP and the screen customization kit is installed the program will be located in the custom program directory otherwise the standard program directory will be used.

Within a screenset the S-CALL function can be used to call a program without having to insert any coding into your program.

If you want to call a business object see the topic Calling Business Objects Overview for information about how this can be done and how parameters are passed.

Sample code

* Calling the Inventory Query without passing a parameter

MOVE "INVPEN" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

* Calling INVPEN and passing a stock code

MOVE "ABC " TO LINK-EXTRA.

MOVE "INVPEN" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM.

* Calling a program and retrieving a value in LINK-EXTRA

MOVE "CUSTOM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM

MOVE LINK-EXTRA TO SAV-PARAMETER-FROM-CUSTOM.

MOVE SPACES TO LINK-EXTRA.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

CALL-PROGRAM-NO-CANCEL, S-CALL, CUSTOM.IMP, CANCEL-PROGRAM


CALL-PROGRAM-NO-CANCEL

The CALL-PROGRAM-NO-CANCEL function is used to call another SYSPRO program or custom Net Express program developed in a SYSPRO style without cancelling it from memory after it exits. This can be used in the case where a program is called many times to improve system performance.

Note that once your program has finished calling the sub program it should use the CANCEL-PROGRAM function.

Care should be taken in designing the program that is called with this function to ensure that the working storage and file usage correctly cater for being called without being initialized each time it is called.

Input parameters

WW-PROG-NAME

The 6 character program name to be called.

LINK-EXTRA

Parameters can be passed in LINK-EXTRA as well as in LNK2.

Output parameters

LINK-EXTRA

Optionally the called program may pass a value back into this field.

LNK2

Optionally the called program may pass a value back into this user defined field.

Remarks

This function is virtually identical to the CALL-PROGRAM function except that the called program is not cancelled from memory after it exits.

This function is typically used when calling a utility program that is called many times in quick succession to improve system performance. When finished you should use the CANCEL-PROGRAM function to cancel it from memory.

If you are not sure which function to use then the CALL-PROGRAM function is recommended.

For details about how to pass parameters using the CALL-PROGRAM-NO-CANCEL function see the description against the CALL-PROGRAM function.

Within a screenset the S-CALLNC function can be used to call a program without having to insert any coding into your program.

If you want to call a business object see the topic Calling Business Objects Overview for information about how this can be done and how parameters are passed.

Sample code

* Calling a utility program passing and receiving a parameter

MOVE "param value" TO LINK-EXTRA.

MOVE "CUSTOM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM-NO-CANCEL.

MOVE LINK-EXTRA TO SAV-PARAMETER-FROM-CUSTOM.

MOVE SPACES TO LINK-EXTRA.

* Later we should CANCEL the program from memory

MOVE "CUSTOM" TO WW-PROG-NAME

MOVE "P" TO WW-PROG-DIR

PERFORM BUILD-PROGRAM-NAME

MOVE WW-RET-PROG TO WW-FILE-NAME.

PERFORM CANCEL-PROGRAM.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

CALL-PROGRAM, CANCEL-PROGRAM, S-CALLNC


CANCEL-PROGRAM

The CANCEL-PROGRAM function is used to cancel a program from memory that has previously been called using the CALL-PROGRAM-NO-CANCEL function.

Note that in a COM environment this routine does nothing.

Input parameters

WW-FILE-NAME

The full path of the program name to be cancelled.

Output parameters

none

Remarks

Many utility programs are called without being cancelled from memory. These typically use the CALL-PROGRAM-NO-CANCEL function.

When these programs have finished (often at ENDJOB) they should use the CANCEL-PROGRAM function.

The programs should generally avoid hard-coding the CANCEL statement as in a COM environment this will cause a failure.

Sample code

* Calling a utility program passing and receiving a parameter

MOVE "param value" TO LINK-EXTRA.

MOVE "CUSTOM" TO WW-PROG-NAME.

PERFORM CALL-PROGRAM-NO-CANCEL.

MOVE LINK-EXTRA TO SAV-PARAMETER-FROM-CUSTOM.

MOVE SPACES TO LINK-EXTRA.

* Later we should CANCEL the program from memory

MOVE "CUSTOM" TO WW-PROG-NAME

MOVE "P" TO WW-PROG-DIR

PERFORM BUILD-PROGRAM-NAME

MOVE WW-RET-PROG TO WW-FILE-NAME.

PERFORM CANCEL-PROGRAM.

Requirements

Version: Included in SYSPRO 6.0 issue 008 and later

Copybooks: standard

See also

CALL-PROGRAM-NO-CANCEL, S-CALL, CUSTOM.IMP, CALL-PROGRAM, Developing for a COM Environment


CANNOT-RUN-STANDALONE

The CANNOT-RUN-STANDALONE function is used to display a message indicating that the current program requires parameters but that none have been passed.

This could happen if an operator used the File > Run… function from the Main menu.

Input parameters

none

Output parameters

none

Remarks

Many programs are called from other programs requiring parameters. If these parameters are not passed as expected then the program should use this function.

Sample code

* Expect a parameter in LINK-EXTRA

IF LINK-EXTRA = SPACES

PERFORM CANNOT-RUN-STANDALONE

GO TO ENDJOB.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Functions by name


CHECK-FILE-EXISTS

The CHECK-FILE-EXISTS function is used to verify the existence of a disk file on the server. It will return a flag indicating the file presence and if the file exists the size of the file.

Input parameters

WW-FILE-NAME

The file name to be tested.

Output parameters

WW-FILE-EXISTS

Returned flag

Y – Files exists

D - Path is a Directory

WW-OUT-SIZE

Size of file in bytes if file exists

DATE-CCYYMMDD

Date file was last modified

WW-TIME

Time file was last modified

Remarks

From SYSPRO 6.0 issue 009 port 01 the file name does not have to be quoted if a spacey file name is passed. Prior to this version you must ensure that if the file name is spacey that you use the QUOTE-VALID-FILE-NAME function to add quotes.

As a byproduct of using this function, if the file exists you will receive the size of the file in bytes. You must only use the file size information if the file exists.

Note that you can also use the CHECK-FILE-EXISTS function to detect if a path is a directory. (in this case you must not use the field WW-OUT-SIZE).

From SYSPRO 6.0 Issue 010 SP1 onwards this function returns the date and time that the file was last modified.

Client/Server implications

This will check the existence of a file on the server in a client/server environment. If you need to check the existence of a file on the client in a client/server environment use CHECK-FILE-EXISTS-ON-CLIENT.

Sample code

*> Check if file exists

MOVE "C:\Syspro\Data\AINVMST.DAT" TO WW-FILE-NAME.

PERFORM CHECK-FILE-EXISTS.

IF FILE-EXISTS = "Y"

MOVE WW-OUT-SIZE TO DISK-FILE-SIZE.

*> Check if temp directory exists

MOVE "C:\TEMP\" TO WW-FILE-NAME.

PERFORM CHECK-FILE-EXISTS.

IF FILE-EXISTS = "D"

GO TO TEMP-DIRECTORY-EXISTS.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

spacey file name, QUOTE-VALID-FILE-NAME, CHECK-FILE-EXISTS-ON-CLIENT


CHECK-FILE-EXISTS-ON-CLIENT

The CHECK-FILE-EXISTS-ON-CLIENT function is used to verify the existence of a disk file on the client in a client/server environment. It will return a flag indicating the file presence and if the file exists the size of the file.

Input parameters

WW-FILE-NAME

The file name to be tested – must have quotes if a spacey file name

Output parameters

WW-FILE-EXISTS

Returned flag

Y – Files exists

D - Path is a Directory

WW-OUT-SIZE

Size of file in bytes if file exists

DATE-CCYYMMDD

Date file was last modified

WW-TIME

Time file was last modified

Remarks

The name must be quoted if it is a spacey file name. Use QUOTE-VALID-FILE-NAME to quote a spacey file name.

Note that you can also use this function to detect if a path is a directory.

This will check the existence of a file on the client in a client/server environment. If you need to check the existence of a file on the server in a client/server environment use CHECK-FILE-EXISTS.

Note that you can also use the CHECK-FILE-EXISTS function to detect if a path is a directory. (in this case you must not use the field WW-OUT-SIZE).

From SYSPRO 6.0 Issue 010 SP1 onwards this function returns the date and time that the file was last modified.

Sample code

MOVE "C:\Syspro\Client\Report.doc" TO WW-FILE-NAME.

PERFORM CHECK-FILE-EXISTS-ON-CLIENT.

IF FILE-EXISTS = "Y"

MOVE WW-OUT-SIZE TO DISK-FILE-SIZE.

Requirements

Version: Included in Encore 5.0 and later. The facility to return a 'D' if the path is a directory is only available from SYSPRO 6.0 issue 009 and later. The Date/Time last modified fields are only returned from SYSPRO 6.0 Issue 010 SP1 and later.

Copybooks: standard

See also

spacey file name, QUOTE-VALID-FILE-NAME, CHECK-FILE-EXISTS


CHECK-FILES-IN-USE

The CHECK-FILES-IN-USE function is used by programs that require exclusive access to one or more files to ensure that they are not being used by other operators.

You pass a list of files that you require exclusive access. If any of these files are being used then the operator will be shown who is using them. If none of the files are in use then a flag will be returned allowing the program to continue.

Input parameters

CHECK-FILES-LIST

This is list of up to 85 files that require exclusive access. Each file consists of a 6 character file code (in uppercase) followed by a space character.

Output parameters

FILES-IN-USE

This is a logical true/false flag indicating whether any of the input files are in use.

Remarks

Various programs – such as period-end programs – require exclusive access to one or more files. This function allows you to verify whether these files are already in use.

If none of the files are in use the FILES-IN-USE flag is false.

If one or more of the files are in use then the operator will be shown a list of the operators currently using the files required. At this time you could contact the operators using the files and ask them to exit – use the refresh function to see if they have actually stopped using the files required. If all operators have stopped using the required files then the FILE-IN-USE flag will also return false allowing your program to continue. However if one or more operators are still using the files the FILES-IN-USE flag will return true and your program should not attempt to open the files.

Warning – if you are an administrator you may logout users at this time. It is important to realize that this does not actually stop the users immediately but simply marks the files as being unused. If the operators really are still logged in then your program will fail when you attempt to open the files exclusively.

Sample code

* Check that A/R Master and Invoice files are not in use

MOVE "ARSMST ARSINV" TO CHECK-FILES-LIST.

PERFORM CHECK-FILES-IN-USE.

IF FILES-IN-USE

GO TO ABORT-AS-FILES-ARE-USED.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also


CHECK-IF-OPER-BELONGS-TO-GROUP

The CHECK-IF-OPER-BELONGS-TO-GROUP function is used to determine whether the current operator belongs to a group. This function allows for primary and sub-groups.

Input parameters

WW-GROUP

Name of group code to be checked.

Output parameters

WW-GROUP-STAT

Returned flag indicating whether the current operator belongs to group WW-GROUP

Space - operator does not belong to group

P - operator belongs to group and the group is the primary group for this operator

S - operator belongs to group and the group is a sub-group for this operator

Remarks

From SYSPRO 6.0 issue 006 an operator can belong to a primary group or a list of sun-groups.

This function is used to determine whether the current operator belongs to a group and whether it is the primary or sub-group.

Sample code

MOVE "SALES" TO WW-GROUP.

PERFORM CHECK-IF-OPER-BELONGS-TO-GROUP.

EVALUATE WW-GROUP-STAT

WHEN "P"

PERFORM BELONGS-TO-PRIMARY-GROUP

WHEN "S"

PERFORM BELONGS-TO-SUB-GROUP

WHEN " "

PERFORM DOES-NOT-BELONG-TO-GROUP

END-EVALUATE.

Requirements

Version: Included in SYSPRO 6.0 issue 006 and later

Copybooks: standard

See also

GET-GROUPS-FOR-OPERATOR, CHECK-MAINTENANCE, CHECK-FILES-IN-USE, CHECK-FILE-EXISTS


CHECK-MAINTENANCE

The CHECK-MAINTENANCE function allows the program to determine whether the Administrator has allowed/disallowed access to this program for the current operator group or role.

Input parameters

none

Output parameters

WW-RET-STAT

Spaces means access allowed

'DENY' means that a browse program has 'browse only' access

'NOBR' means that a browse program has been completely 'denied' access

Remarks

The standard routines in PROBEGIN.PRO verify whether the current program can be run. Access is either 'Allowed' or 'Denied'. When 'Denied' the system will generate an 'Access denied' message and branch to ENDJOB.

You can prevent this test by moving 'N' to the field CHECK-ACCESS before PROBEGIN.PRO is executed.

If your program prevents PROBEGIN.PRO from checking the access you can check it yourself using the CHECK-MAINTENANCE function.

The administrator can allow/deny access to most programs using the group code or role.

Note that browse programs can be set to one of three values:

- 'Denied' means that the browse cannot be run at all - you will receive an 'Access Denied' message.

- 'Browse Only' means that you can run the browse program, view/select items but you cannot maintain items.

- 'Allowed' means you have full access to the browse program including any maintenance functions.

There is a similar function called CHECK-MAINTENANCE-OTHER-PROG that allows you to check whether another program can be run.

Sample code

** Check if maintenance allowed

MOVE 1 TO D-MNT-FLG. *> Assume 'allowed'

PERFORM CHECK-MAINTENANCE.

IF WW-RET-STAT NOT = SPACES

MOVE 0 TO D-MNT-FLG. *> Can be run but no 'maintenance'

*

** If special flag set indicating browse cannot be run

** then return 'Access denied' message and exit

IF WW-RET-STAT = "NOBR"

MOVE "DENY" TO LINK-EXTRA

MOVE "A" TO LINK-ERR-FLAG

MOVE "IMPWER" TO WW-PROG-NAME

MOVE "CALLPG" TO WW-FUNCTION

PERFORM WW

GO TO ENDJOB.

Requirements

Version: Included in Encore 5.0 and later. 'NOBR' returned from SYSPRO 6.0 issue 008 and later.

Copybooks: Standard

See also

ENDJOB, CHECK-MAINTENANCE-OTHER-PROG


CHECK-MAINTENANCE-OTHER-PROG

The CHECK-MAINTENANCE-OTHER-PROG function allows the program to determine whether the Administrator has allowed/disallowed access to another program for the current operator group or role.

Input parameters

WW-PROG-NAME

Program name to be tested

Output parameters

BRW-MAINT-FLAG

'F' means access allowed

'N' means that a browse program has 'browse only' access

'B' means that a browse program has been completely 'denied' access

Remarks

The standard routines in PROBEGIN.PRO verify whether the current program can be run. Access is either 'Allowed' or 'Denied'. When 'Denied' the system will generate an 'Access denied' message and branch to ENDJOB.

However this function can be used to determine whether another program can be run.

If you want to determine whether the current program can be run use the CHECK-MAINTENANCE function.

Sample code

** Check if maintenance allowed for program 'CMSPEN'

MOVE "CMSPEN" TO WW-PROG-NAME.

PERFORM CHECK-MAINTENANCE-OTHER-PROG.

IF BRW-MAINT-FLAG = "F"

PERFORM FULL-ACCESS-ALLOWED

ELSE

PERFORM ACCESS-DENIED

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: Standard

See also

ENDJOB, CHECK-MAINTENANCE


CHECK-SHARED-TABLE

The CHECK-SHARED-TABLE function is used to determine whether a standard SYSPRO table name should use the current company id to access it's data or whether a shared Inventory or shared Ledger id should be used instead.

Input parameters

WW-SHARED-TABLE

Table name to be tested.

Output parameters

WW-SHARED-FLAG

Returned flag indicating whether the table is shared or not

Space - Table is not shared

I - Shared Inventory id (use IM0SHINV)

G - Shared Ledger id (use IM0SHGEN)

WW-SHARED-COMP

Returned company id to be used to build table/file name

Remarks

This function is useful where you need to build a physical disk file name or access a database table name for the correct company. This function is of particular use when processing SYSPRO tables using a data dictionary.

The majority of SYSPRO data files use the current company id as a prefix to the file name and SYSPRO tables store the physical table in the current SYSPRO company database.

However a few programs require to identify the ISAM file name or Database..Table name directly. This is especially useful when developing applications to handle SYSPRO data generically or to access data from companies other than the current one.

The CHECK-SHARED-TABLE function accepts a table name as input (e.g. 'InvMaster') and returns two fields. The first is a flag indicating whether the table is shared inventory, shared ledger or neither. The first is the actual shared id (or current company id) for the table in question.

See the topic Shared Inventory Files for more information.

Sample code

MOVE "InvMaster" TO WW-SHARED-TABLE.

PERFORM CHECK-SHARED-TABLE.

EVALUATE WW-SHARED-FLAG

WHEN "I" PERFORM SHARED-INV-LOGIC

WHEN "G" PERFORM SHARED-GEN-LOGIC

WHEN OTHER PERFORM NOT-SAHRED-LOGIC

END-EVALUATE.

Requirements

Version: Included in SYSPRO 6.0 issue 010 port 16 and later

Copybooks: standard

See also

Shared Inventory Files, BUILD-FILE-NAME, CHECK-SHARED-TYPE


CHECK-SHARED-TYPE

The CHECK-SHARED-TYPE function is used to determine whether a Custom Form field is related to a current company id or whether a shared Inventory or shared Ledger id should be used instead.

Input parameters

WW-SHARED-TYPE

Custom form type to be tested (e.g. 'STK' or 'ORD')

Output parameters

WW-SHARED-FLAG

Returned flag indicating whether the table where the Custom Form type data is stored is shared or not

Space - Table is not shared

I - Shared Inventory id (use IM0SHINV)

G - Shared Ledger id (use IM0SHGEN)

WW-SHARED-COMP

Returned company id to be used to build table/file name

Remarks

This function is useful where you need to generically process information about a Custom Form.

The majority of SYSPRO data files use the current company id as a prefix to the file name and SYSPRO tables store the physical table in the current SYSPRO company database.

However a few programs require to identify the ISAM file name or Database..Table name directly. This is especially useful when developing applications to handle SYSPRO data generically or to access data from companies other than the current one.

The CHECK-SHARED-TYPE function accepts a Custom Form type (such as 'STK' or 'ORD'). If you need to process the data related to the Custom Form type you require to know how to open the physical file/table based on this type. This function returns the company id of the data file to be opened.

See the topic Shared Inventory Files for more information.

Sample code

MOVE "STK" TO WW-SHARED-TYPE.

PERFORM CHECK-SHARED-TYPE.

EVALUATE WW-SHARED-FLAG

WHEN "I" PERFORM SHARED-INV-LOGIC

WHEN "G" PERFORM SHARED-GEN-LOGIC

WHEN OTHER PERFORM NOT-SAHRED-LOGIC

END-EVALUATE.

Requirements

Version: Included in SYSPRO 6.0 issue 010 port 16 and later

Copybooks: standard

See also

Shared Inventory Files, BUILD-FILE-NAME, CHECK-SHARED-TABLE


CHECK-USER-STILL-VALID

The CHECK-USER-STILL-VALID function is used to verify that the user is still indicated as logged-in to SYSPRO. This can assist in an operator being notified that an Administrator has attempted to log them out prematurely – for example when performing system maintenance.

The user will receive a message that they have been logged out, the job logging will be updated with this message and the operator will not be able to run further programs.

Input parameters

none

Output parameters

LINK-ALLOW-CALL

This flag is set to N to indicate that the user had been logged out prematurely by an administrator.

Remarks

This function can be used by posting programs to ensure that the administrator has not logged out the operator prematurely.

A job logging message will indicate that the operator was logged out.

Sample code

* Test if operator is still logged-in

PERFORM CHECK-USER-STILL-VALID.

IF LINK-ALLOW-CALL = "N"

GO TO ENDJOB.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also


CLEAR-AP-PAY-LOCK

The CLEAR-AP-PAY-LOCK function is used to clear a lock previously acquired to process the A/P Payments Release file.

It is important to acquire a lock for a supplier before processing the A/P Payment Release information for the supplier. See the GET-AP-PAY-LOCK function.

Input parameters

LINK-EXTRA

You must pass the supplier code to be unlocked to this field

Output parameters

none

Remarks

If you require to process A/P Payments for a supplier then you should acquire a lock. This function is then used to clear the lock.

Sample code

* About to process A/P Payment Release for supplier

MOVE APSMST-SUP TO LINK-EXTRA. *> Move in supplier code

PERFORM GET-AP-PAY-LOCK.

IF LINK-EXTRA = SPACES

PERFORM PROCESS-PAYMENTS-FOR-SUPPLIER

MOVE D-SUPPLIER TO LINK-EXTRA

PERFORM CLEAR-AP-PAY-LOCK

ELSE

MOVE SPACES TO LINK-EXTRA

PERFORM UNABLE-TO-ACQUIRE-LOCK.

Requirements

Version: Included in Encore 5.1 issue 004 and later.

Copybooks: standard

See also

GET-AP-PAY-LOCK, DELETE-AP-PAY-LOCK-FILE


CLEAR-FORCE-CHANGE-PASSWORD

The CLEAR-FORCE-CHANGE-PASSWORD function is used to clear the flag against an operator that forces an operator to change their operator password the next time they login.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being set.

You must enter 'ADMOPR' to specify operator passwords.

LINK-PASS-CMP

This is the company id of the key required.

You must enter spaces to specify operator passwords.

LINK-PASS-KEY

This is the key of the item being protected.

You must enter the operator code.

Output parameters

None

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The CLEAR-FORCE-CHANGE-PASSWORD function is used to clear the 'force password change' flag against the specified operator code.

There is a SET-FORCE-CHANGE-PASSWORD function that sets the 'force password change' flag.

Sample code

* Clear flag that could force operator 'NEW' to change their password

MOVE SPACES TO LINK-PASS.

MOVE "NEW" TO LINK-PASS-KEY. *> Operator code

PERFORM CLEAR-FORCE-CHANGE-PASSWORD.

Requirements

Version: Included in SYSPRO 6.1 port 29 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD, SET-FORCE-CHANGE-PASSWORD


CLEAR-GL-ENT-LOCK

The CLEAR-GL-ENT-LOCK function is used to clear a lock previously acquired to process the G/L entries file.

It is important to acquire a lock before adding or posting to a G/L Entries file. See the GET-GL-ENT-LOCK-EXCLUSIVE and GET-GL-ENT-LOCK-SHARED functions.

Input parameters

LINK-EXTRA-2

If you wish to clear a lock on a company other than the current company then move in the company id to this field.

Output parameters

none

Remarks

If you require to add new entries to the G/L Entries file the you should acquire a lock. This function is then used to clear the lock.

Sample code

* Update G/L Entries

PERFORM GET-GL-ENT-LOCK-SHARED.

IF LINK-EXTRA = SPACES

PERFORM READ-GL-ENTRIES

ELSE

PERFORM UNABLE-TO-ACQUIRE-LOCK.

PERFORM CLEAR-GL-ENT-LOCK.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

GET-GL-ENT-LOCK-EXCLUSIVE, GET-GL-ENT-LOCK-SHARED


CLEAR-WIP-TRIAL-LOCK

The CLEAR-WIP-TRIAL-LOCK function is used to clear a lock previously acquired to process the WIP Trial load file.

It is important to acquire a lock before changing the WIP Trial load file. See the GET-WIP-TRIAL-LOCK-EXCLUSIVE function.

Input parameters

LINK-EXTRA-2

If you wish to clear a lock on a company other than the current company then move in the company id to this field.

Output parameters

none

Remarks

If you require to change the WIP Trial load files then you should acquire a lock. This function is then used to clear the lock.

Sample code

* Update WIP Trial Load

PERFORM GET-WIP-TRIAL-LOCK-SHARED.

IF LINK-EXTRA = SPACES

PERFORM UPDATE-WIP-TRIAL-LOAD

ELSE

PERFORM UNABLE-TO-ACQUIRE-LOCK.

PERFORM CLEAR-WIP-TRAIL-LOCK.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

GET-WIP-TRIAL-LOCK-EXCLUSIVE


CLR-PRINT-BY-FUNCTION

The CLR-PRINT-BY-FUNCTION function is used to clear saved printer settings against a specific program function for the current operator. These are saved using the SET-PRINT-BY-FUNCTION function.

Once cleared the current default printer will be used when printing the document.

This is part of the Printer per function facility.

Input parameters

LINK-PRINT-FUNCT

This is a 6 character field that defines the document to be used. It is recommended that codes beginning with USR are used by third parties to avoid possible conflict with standard codes.

Output parameters

none

Remarks

This function removes current printer settings for the function/current operator.

Use GET-PRINT-BY-FUNCTION to determine whether there are any printer settings for the function/operator code combination.

The printer settings are stored in two C-ISAM files called ADMPRF.DAT and ADMPRH.DAT.

Sample code

*

** Clear the current printer settings against document 'USRINV'

CLEAR-USRINV.

MOVE "USRINV" TO LINK-PRINT-FUNCT.

PERFORM CLR-PRINT-BY-FUNCTION.

*

** Restore printer settings for document 'USRINV'

RESTORE-USRINV.

MOVE "USRINV" TO LINK-PRINT-FUNCT.

PERFORM RETRIEVE-PRINT-BY-FUNCTION.

*

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE-NO-PRINT. *> Abort without printing

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

Printer per function, PRINT-OPEN, PRINT-CLOSE, SET-PRINT-BY-FUNCTION, RETRIEVE-PRINT-BY-FUNCTION, GET-PRINT-BY-FUNCTION


CMS-READ-CONTACT-GUID-FRM-NAME

The CMS-READ-CONTACT-GUID-FRM-NAME function is used to retrieve a ContactId passing a Contact Name.

Input parameters

WW-CRMCON-FULL-NAME

Contact full name (this is not case sensitive).

Output parameters

WW-CRMCON-GUID

ContactId returned as a GUID in GUID16 format.

WW-CRMCON-PREF-NAME

Contact preferred name returned as a 50 character field.

WW-CRMCON-FULL-NAME

Contact full name returned in UPPERCASE.

Remarks

This function is to be used to retrieve a ContactId when you have been passed a Contact Name. The Contact Name is case insensitive. Note that if two or more Contacts have the same name then only one ContactId will be returned.

It is recommended that you read the topic Using GUIDs for additional information.

Sample code

* We have been passed a Contact Name

MOVE PASSED-NAME TO WW-CRMCON-FULL-NAME.

PERFORM CMS-READ-CONTACT-GUID-FRM-NAME.

MOVE WW-CRMCON-GUID TO CONTACT-GUID.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP1 port 15 and later.

Copybooks: standard

See also

Data Dictionary Conventions, Using GUIDs, CMS-READ-CONTACT-NAME-FRM-GUID, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16.


CMS-READ-CONTACT-NAME-FRM-GUID

The CMS-READ-CONTACT-NAME-FRM-GUID function is used to retrieve a Contact Name passing a 16 byte ContactId.

Input parameters

WW-CRMCON-GUID

ContactId passed in GUID16 format.

Output parameters

WW-CRMCON-FULL-NAME

Contact full name returned as a 100 character field.

WW-CRMCON-PREF-NAME

Contact preferred name returned as a 50 character field.

Remarks

This function is to be used to retrieve a Contact Name when you have been passed a ContactId.

It is recommended that you read the topic Using GUIDs for additional information.

Sample code

* We have been passed a ContactId in X(16) format

MOVE PASSED-GUID TO WW-CRMCON-GUID.

PERFORM CMS-READ-CONTACT-NAME-FRM-GUID.

MOVE WW-CRMCON-FULL-NAME TO CONTACT-FULL-NAME.

MOVE WW-CRMCON-PREF-NAME TO CONTACT-PREFERRED-NAME.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP1 port 15 and later.

Copybooks: standard

See also

Data Dictionary Conventions, Using GUIDs, CMS-READ-CONTACT-GUID-FRM-NAME, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16.


COM-ERROR-MSG

The COM-ERROR-MSG function is used to return a language independent message given a message number. It is primarily designed to be used for component programs called from e.net solutions.

These messages can be up to 600 characters long and may be parameterised.

Input parameters

LINK-COM-MSG

A 6 digit message number - See ???STD.WRK files for 78 levels defining valid numbers.

LINK-EXTRA

A value to replace optional parameter %1

LINK-EXTRA-2

A value to replace optional parameter %2

LINK-EXTRA-3

A value to replace optional parameter %3

Output parameters

LINK-EXTRA

The message returned.

LINK-COM-RETURN

This value contains the 6 digit message number.

Remarks

This function is virtually identical to the LOOKUP-MSG function except that it updates LINK-COM-RETURN.

This function is used to return messages from the message files stored in the program directory. See the topic Error Handling for the file names and set numbers used.

Each standard message has a 78 level field defining the message number to be used. These numbers are 6 digit numbers consisting of a 2 digit set number and a 4 digit message number. The set number is used to group messages. Note that certain set numbers are reserved for future use. See the working storage copybooks ???STD.WRK for the 78 level numbers.

Some messages require between 1 and 3 optional parameters represented by %1, %2 and %3. When these parameters are defined in a message you must pass their values in the appropriate LINK-EXTRA fields - See Input parameters above.

If you have set your LANG environment variable (on the client in a client/server environment) to a two digit language code then this will be used - otherwise the language code defined against the operator will be used.

Sample code

MOVE COM-MSG-INV-STK-NOT TO LINK-COM-MSG. *> Stock code '%1' not found

MOVE STOCK-CODE TO LINK-EXTRA.

PERFORM COM-ERROR-MSG.

GO TO ENDJOB.

Requirements

Version: Included in Encore 5.1 issue 004 and later

Copybooks: standard

See also

Error Handling, LOOKUP-MSG, LOOK-UP-ERROR


COMER

The COMER function is used to verify the value of the file status code field STAT-CODE and if an error occurs then an appropriate message is displayed.

In addition if a transaction is in process a ROLLBACK-TRANSACTION will be issued.

See the topic Testing File Status Codes for a summary of which file status codes should be tested after each file operation.

Input parameters

STAT-CODE

This is a two character field that determines the status of the last file access.

The standard generic file routines automatically update this field after every file access so generally you should not set or change this field.

ERRFIL

This is the disk file name of the file being processed.

The standard generic file routines automatically update this field after every file access so generally you should not set or change this field.

ERRMES

This is a flag indicating what file access was being attempted.

The standard generic file routines automatically update this field after every file access so generally you should not set or change this field.

ERRKEY

This is the primary key of the C-ISAM file being processed.

The standard generic file routines automatically update this field after every file access so generally you should not set or change this field.

ERRFCD

This is the 6 character file code being accessed.

This field is useful for the system as if you use a blank file name by mistake the offending file access can be determined - also the system can determine the description of the file being accessed by looking up the file code from IMPFIL.IMP.

COMER-TO-ENDJOB

This flag can be used to prevent the COMER function branching to ENDJOB if a failure occurs. By default COMER will branch to ENDJOB.

N – No branch to ENDJOB required

Output parameters

none

Remarks

Whenever a file operation is performed a two character status code field called STAT-CODE is updated.

If a program expects a successful file operation then immediately after the file operation you should use the COMER function. If the file operation was successful then this returns immediately, however if a failure is detected then an appropriate message will be displayed and the routine will GO TO ENDJOB.

In addition a Job Logging message will be output indicating details of the failure.

STAT-CODE is divided into two single character fields. The values of these are defined by the ANSI 85 standards. For more detail see File Status Codes.

Common file status conditions have been defined in STANDARD.WRK using logical 88 levels. The most common of these is the value STAT-OK which is logically true when the file operation is successful.

By default the COMER function branches to ENDJOB when an error occurs. If you want to control the program flow yourself then you can move N to COMER-TO-ENDJOB and after COMER check the NOT STAT-OK as shown below. Remember to reset the COMER-TO-ENDJOB back to Y when required. for example:

MOVE "N" TO COMER-TO-ENDJOB.

PERFORM COMER.

IF NOT STAT-OK

PERFORM HANDLE-ERROR-CONDITION.

MOVE "Y" TO COMER-TO-ENDJOB.

The COMER function also can handle other non-file related error codes. For example SQL Server optimization error codes.

Important note about COMER inside a transaction

By default when you issue a PERFORM COMER function it will detect any file errors, display a message and branch to ENDJOB so that the program terminates gracefully.

However when inside a transaction the default behaviour is to detect any file errors, display a message and then continue with the processing - i.e. by default it DOES NOT BRANCH TO ENDJOB.

If you wish to ensure that any unexpected file error from within a transaction exits your program you can move 'E' to the field COMER-TO-ENDJOB.

For example you will often use the following code fragment when beginning a transaction:

PERFORM BEGIN-TRANSACTION.

MOVE "E" TO COMER-TO-ENDJOB.

Sample code

* Read stock code for known item

MOVE "B100" TO INVMST-KEY.

PERFORM INVMST-READ-WAIT.

PERFORM COMER.

* Update long stock description

MOVE "Long stock description" TO INVMST-LONG.

PERFORM INVMST-REWRITE.

PERFORM COMER.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

File Status Codes, Testing File Status Codes, ROLLBACK-TRANSACTION, ENDJOB


COMMIT-TRANSACTION

The COMMIT-TRANSACTION function is used to complete a logical business transaction that was started using the BEGIN-TRANSACTION function.

See the Transaction Processing topic and BEGIN-TRANSACTION function for additional details.

Input parameters

none

Output parameters

LINK-SQL-TRANSACT

This is an indicator showing whether a transaction is in progress. You can read this value but you must not change it. This function always sets it to spaces.

Y - Yes

Remarks

Transaction Processing is a concept that ensures that all data added, changed or deleted as part of a logical process is either completed successfully or completely undone – as if it had never happened.

See the description against BEGIN-TRANSACTION for more details.

Note that on a C-ISAM base company this will release all record lock held by the program.

Sample code

* Start a transaction

MOVE "Debit A $100 and Credit B $100" TO LINK-SQL-TRAN-TEXT.

MOVE "E" TO COMER-TO-ENDJOB.

PERFORM BEGIN-TRANSACTION.

* Credit A with $100

MOVE COMPID TO GENMST-CMP.

MOVE "A" TO GENMST-ACC.

PERFORM GENMST-READ.

PERFORM COMER.

ADD 100 TO GENMST-DR. *> Add to Period to date Debits $100

ADD 100 TO GENMST-CBAL. *> Update balance

PERFORM GENMST-REWRITE.

PERFORM COMER

* Credit B with $100

MOVE COMPID TO GENMST-CMP.

MOVE "B" TO GENMST-ACC.

PERFORM GENMST-READ.

PERFORM COMER.

ADD 100 TO GENMST-CR. *> Add to Period to date Credits

SUBTRACT 100 FROM GENMST-CBAL. *> Update balance

PERFORM GENMST-REWRITE.

PERFORM COMER

* Done

PERFORM COMMIT-TRANSACTION.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Transaction Processing, BEGIN-TRANSACTION, ROLLBACK-TRANSACTION, COMER


CONTROL-ERROR

The CONTROL-ERROR function is used to allow a program to accumulate one or more control messages at the start of the program and to present the user with these messages.

Input parameters

CTL-ERR(x)

A list of error message numbers relating to control records missing or other initialisation problems.

Output parameters

none

Remarks

This function is typically used when a program first loads, before any user interface has been shown, to show a list of initialisation problems.

The table defined by CTL-ERR(x) allows up to 20 error messages to be built. The 3 digit message numbers are defined in STANDARD.WRK by 78 level fields beginning with CTL-ERR-.

These include

78 CTL-ERR-GM-00 VALUE 130.

78 CTL-ERR-MT-00 VALUE 131.

78 CTL-ERR-AP-00 VALUE 132.

78 CTL-ERR-AR-00 VALUE 133.

78 CTL-ERR-IN-00 VALUE 134.

etc…

Typically the subscript XX4 is used to accumulate a list of the problems. See the sample code below.

Sample code

MOVE ZERO TO XX4.

*

** Read the A/R control record

MOVE "CTL" TO ARSCTL-KEY.

PERFORM ARSCTL-READ.

IF NOT STAT-OK

ADD 1 TO XX4

MOVE CTL-ERR-AR-00 TO CTL-ERR(XX4).

*

** Read the Inventory control record

MOVE "CTL" TO INVCTL-KEY.

PERFORM INVCTL-READ.

IF NOT STAT-OK

ADD 1 TO XX4

MOVE CTL-ERR-IN-00 TO CTL-ERR(XX4).

*

IF XX4 > ZERO

PERFORM CONTROL-ERROR.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also


CONVERT-ASCII-TO-HEX

The CONVERT-ASCII-TO-HEX function is used to convert a string of ASCII characters to a Hex (Hexadecimal) string.

Input parameters

WW-ASCII

The ASCII string to be converted – current maximum of 500 characters.

WW-ASCII-LEN

The length of the ASCII string.

Output parameters

WW-HEX

The generated HEX string.

Remarks

This function is used to convert a string of ASCII characters to it's Hexadecimal equivalent.

You must pass the length of the ASCII string as spaces are valid ASCII characters and will be converted to '20' Hex.

For example the ASCII string 'ABC 123' (note space between 'C' and '1') with a length of 7 will be converted to '41424320313233' Hex.

There is a function CONVERT-HEX-TO-ASCII for reversing the conversion.

The sample program SDKHEX demonstrates use of this function.

Sample code

* Convert ASCII to Hex

MOVE "ABC 123" TO WW-ASCII. *> 'ABC 123'

MOVE 7 TO WW-ASCII-LEN.

PERFORM CONVERT-ASCII-TO-HEX.

MOVE WW-HEX TO D-HEX. *> '41424320313233'

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 16 and later.

Copybooks: standard

See also

CONVERT-HEX-TO-ASCII, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16


CONVERT-GUID16-TO-GUID36

SYSPRO SDK

Function Reference

CONVERT-GUID16-TO-GUID38

The CONVERT-GUID16-TO-GUID38 function is used to convert a GUID in 16 byte (128 bit) format to the industry standard 38 character format that can be used for presentation.

Input parameters

WW-GUID16

A 16 byte (128 bit) GUID.

Output parameters

WW-GUID38

The GUID in a 38 character industry standard format.

Remarks

This function is used to convert a GUID in 16 byte (128 bit) format to industry standard 38 character format that can be used for presentation.

For example the 16 byte GUID value

1234567890123456

is converted to the following 38 character format:

{34333231-3635-3837-3930-313233343536}

This is a Hexadecimal representation of each input character with dashes between sections. The first three sections are byte-swapped.

Note: The above GUID '1234567890123456' is not a valid GUID but is used to demonstrate how the 38 character industry standard format is converted and transposed from the original 16 byte format.

There is a function CONVERT-GUID38-TO-GUID16 for reversing the conversion.

It is recommended that you read the topic Using GUIDs for additional information.

See the topic Data Dictionary Conventions for information about how to define a GUID in a record layout.

The sample program SDKHEX demonstrates use of this function.

Sample code

* Convert GUID16 to GUID38

MOVE "1234567890123456" TO WW-GUID16.

PERFORM CONVERT-GUID16-TO-GUID38.

MOVE WW-GUID38 TO D-GUID38.

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 16 and later. Note that from SYSPRO 6.0 issue 010 the field GUID36 was changed to GUID38 so that the GUID was surrounded in brackets {}.

Copybooks: standard

See also

Data Dictionary Conventions, Using GUIDs, CONVERT-GUID38-TO-GUID16, CONVERT-ASCII-TO-HEX, CONVERT-HEX-TO-ASCII, CMS-READ-CONTACT-GUID-FRM-NAME, CMS-READ-CONTACT-NAME-FRM-GUID.


CONVERT-GUID36-TO-GUID16

SYSPRO SDK

Function Reference

CONVERT-GUID38-TO-GUID16

The CONVERT-GUID38-TO-GUID16 function is used to convert a GUID from an industry standard 38 character format to a 16 byte (128 bit) format.

Input parameters

WW-GUID38

A GUID in a 38 character industry standard format.

Output parameters

WW-GUID16

The result in a 16 byte (128 bit) GUID format.

Remarks

This function is used to convert a GUID from an industry standard 38 character format to a 16 byte (128 bit) format suitable for storing on a file or passing to another application.

For example the 38 character format GUID value:

{34333231-3635-3837-3930-313233343536}

is converted to the following 16 byte value:

1234567890123456

The 16 byte GUID format contains the ASCII values of the Hex pairs with all dashes removed. The first three sections are byte-swapped.

Note: The above GUID '{34333231-3635-3837-3930-313233343536}' is not a valid GUID but is used to demonstrate how the 16 byte GUID is converted and transposed from the original 38 character industry standard format.

There is a function CONVERT-GUID16-TO-GUID38 for reversing the conversion.

It is recommended that you read the topic Using GUIDs for additional information.

See the topic Data Dictionary Conventions for information about how to define a GUID in a record layout.

The sample program SDKHEX demonstrates use of this function.

Sample code

* Convert GUID38 to GUID15

MOVE "{34333231-3635-3837-3930-313233343536}" TO WW-GUID38.

PERFORM CONVERT-GUID38-TO-GUID16.

MOVE WW-GUID16 TO D-GUID16.

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 16 and later. Note that from SYSPRO 6.0 issue 010 the field GUID36 was changed to GUID38 so that the GUID was surrounded in brackets {}.

Copybooks: standard

See also

Data Dictionary Conventions, Using GUIDs, CONVERT-GUID16-TO-GUID38, CONVERT-ASCII-TO-HEX, CONVERT-HEX-TO-ASCII, CMS-READ-CONTACT-GUID-FRM-NAME, CMS-READ-CONTACT-NAME-FRM-GUID.


CONVERT-HEX-TO-ASCII

The CONVERT-HEX-TO-ASCII function is used to convert a string of 2 character Hexadecimal characters to their ASCII equivalent..

Input parameters

WW-HEX

The space-terminated HEX string to be converted - current maximum 1000 characters.

Output parameters

WW-ASCII

The converted ASCII string.

Remarks

This function is used to convert a string of Hexadecimal characters to it's ASCII equivalent.

Note that the Hex string is space terminated and must consist of pairs of Hex characters.

Each Hex character must consist of the characters '0-9' and 'A-Z' (uppercase).

For example the Hex string '41424320313233' will be converted to 'ABC 123' (note the space character between the 'C' and '1').

There is a function CONVERT-ASCII-TO-HEX for reversing the conversion.

The sample program SDKHEX demonstrates use of this function.

Sample code

* Convert Hex to ASCII

MOVE "41424320313233" TO WW-HEX. *> '41424320313233'

PERFORM CONVERT-HEX-TO-ASCII.

MOVE WW-ASCII TO D-ASCII. *> 'ABC 123'

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 16 and later.

Copybooks: standard

See also

CONVERT-ASCII-TO-HEX, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16


CONVERT-LOWER-CASE

The CONVERT-LOWER-CASE function is used to convert a string in any case to lowercase.

Input parameters

WW-FILE-NAME

The string to be converted – current maximum of 258 characters.

Output parameters

WW-FILE-NAME

The converted string.

Remarks

This routine simplifies generating text message based on user input.

There are similar routines CONVERT-UPPER-CASE and CONVERT-UPPER-LOWER.

Sample code

* Build and open customer file from current company

MOVE "THIS is MiXeD case TEXT" TO MIXED-CASE-TEXT.

*

* Generate 'This is mixed case text'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-UPPER-LOWER.

MOVE WW-FILE-NAME TO INITIAL-UPPER-REST-LOWER.

*

* Generate 'this is mixed case text'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-LOWER-CASE.

MOVE WW-FILE-NAME TO ALL-LOWER-CASE.

*

* Generate 'THIS IS MIXED CASE TEXT'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-UPPER-CASE.

MOVE WW-FILE-NAME TO ALL-UPPER-CASE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

CONVERT-UPPER-CASE, CONVERT-UPPER-LOWER


CONVERT-PATH-PRINT

The CONVERT-PATH-PRINT function is used to abbreviate a long file name. Often there is not space to print or display a full 255 character file name. This routine helps abbreviate the file name in a consistent manner.

Input parameters

INFILE-NAME

This is the full file name that may need to be abbreviated.

MAX-FILE-LENGTH

This is the number of characters available. The abbreviated name will not be longer than this value. Define a number between 20 and 255.

Output parameters

OUTFILE-NAME

The output file name that will not be longer that MAX-FILE-LENGTH

Remarks

Whenever you print or display a file name and do not have the space available in the case of a very long file name use this function to abbreviate the name consistently.

Sample code

MOVE LONG-FILE-NAME TO INFILE-NAME.

MOVE LENGTH OF SHORT-FILE-NAME TO MAX-FILE-LENGTH.

PERFORM CONVERT-PATH-PRINT.

MOVE OUTFILE-NAME TO SHORT-FILE-NAME.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

BUILD-FILE-NAME


CONVERT-UPPER-CASE

The CONVERT-UPPER-CASE function is used to convert a string in any case to uppercase.

Input parameters

WW-FILE-NAME

The string to be converted – current maximum of 258 characters.

Output parameters

WW-FILE-NAME

The converted string.

Remarks

This routine simplifies generating text message based on user input.

There are similar routines CONVERT-LOWER-CASE and CONVERT-UPPER-LOWER.

Sample code

* Build and open customer file from current company

MOVE "THIS is MiXeD case TEXT" TO MIXED-CASE-TEXT.

*

* Generate 'This is mixed case text'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-UPPER-LOWER.

MOVE WW-FILE-NAME TO INITIAL-UPPER-REST-LOWER.

*

* Generate 'this is mixed case text'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-LOWER-CASE.

MOVE WW-FILE-NAME TO ALL-LOWER-CASE.

*

* Generate 'THIS IS MIXED CASE TEXT'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-UPPER-CASE.

MOVE WW-FILE-NAME TO ALL-UPPER-CASE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

CONVERT-LOWER-CASE, CONVERT-UPPER-LOWER


CONVERT-UPPER-LOWER

The CONVERT-UPPER-LOWER function is used to convert a string in any case so that the initial character is capitalised and the rest is in lowercase.

Input parameters

WW-FILE-NAME

The string to be converted – current maximum of 258 characters.

Output parameters

WW-FILE-NAME

The converted string.

Remarks

This routine simplifies generating text message based on user input.

There are similar routines CONVERT-LOWER-CASE and CONVERT-UPPER-CASE.

Sample code

* Build and open customer file from current company

MOVE "THIS is MiXeD case TEXT" TO MIXED-CASE-TEXT.

*

* Generate 'This is mixed case text'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-UPPER-LOWER.

MOVE WW-FILE-NAME TO INITIAL-UPPER-REST-LOWER.

*

* Generate 'this is mixed case text'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-LOWER-CASE.

MOVE WW-FILE-NAME TO ALL-LOWER-CASE.

*

* Generate 'THIS IS MIXED CASE TEXT'

MOVE MIXED-CASE-TEXT TO WW-FILE-NAME.

PERFORM CONVERT-UPPER-CASE.

MOVE WW-FILE-NAME TO ALL-UPPER-CASE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

CONVERT-LOWER-CASE, CONVERT-UPPER-CASE


COPY-FILE-ON-SERVER

The COPY-FILE-ON-SERVER function is used to copy a file on the server to another file name on the server.

In a Client/Server environment this will be issued on the server. This may be a Windows or Unix system.

Care must be taken to ensure that appropriate files are not overwritten.

Input parameters

LINK-EXTRA-1

This is the source file to be copied. It must be quoted if spacey.

LINK-EXTRA-2

This is the target file to be copied. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to copy the file.

Zero - Yes

Remarks

If the required file names are spacey file names then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

In a client/server system the command is executed on the server.

In a mapped drive system the command is executed on the client PC.

Note that there is currently no equivalent function to copy files on the Client PC in a client/server environment.

See the function COPY-FILE-TO-CLIENT and COPY-FILE-TO-SERVER to transfer a file from the server to a client PC in a client/server environment.

Sample code

* Copy a file on the server

IF LINK-OS = "U"

MOVE "/tmp/abc.txt " TO LINK-EXTRA-1

MOVE "/tmp/abcnew.txt " TO LINK-EXTRA-2

ELSE

MOVE "C:\TEMP\ABC.TXT " TO LINK-EXTRA-1

MOVE "C:\TEMP\ABCNEW.TXT" TO LINK-EXTRA-2.

PERFORM COPY-FILE-ON-SERVER.

IF LINK-IMPWSH-STA = ZERO

GO TO FILE-COPIED-SUCCESSFULLY.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file names, DEL-FILE-ON-SERVER, COPY-FILE-TO-CLIENT, COPY-FILE-TO-SERVER, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSCOPYS


COPY-FILE-TO-CLIENT

The COPY-FILE-TO-CLIENT function is used to transfer a file from the server system to the client PC.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Input parameters

LINK-EXTRA-1

This is the source file to be copied. It must be quoted if spacey.

LINK-EXTRA-2

This is the target file to be copied. It must be quoted if spacey (see LINK-IMPWSH-DIR)

LINK-IMPWSH-DIR

This is a flag indicating the target location on the Client PC.

T | a temporary client file name will be generated. See Output parameters
S | the file will be copied to the screenset directory and if there are any associated user controls in BASE\BIN they will also be transferred
B | the file will be transferred to the BASE directory
I | the file will be transferred to the BASE\BIN directory
F | LINK-EXTRA-2 contains the full path for the target file

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to copy the file.

Zero – Yes

LINK-EXTRA-2

If the function T was defined in LINK-IMPWSH-DIR this contains the full path name of the temporary file generated on the client.

Remarks

If the required file names are spacey file names then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function works by reading and transferring blocks of up to 60,000 bytes at a time across the network, reconstructing the target file on the client PC. Therefore files up to 60,000 bytes in size are transferred with a single network transition and will be fast. Files requiring relatively few network transitions will also be relatively fast. Large files (half a megabyte or more?) may take a noticeable time to be transferred depending on the network speed.

Note that this function does not use any operating system commands and does not use ftp. The copy is a binary transfer therefore text files may or may not be accessible depending on the source operating system.

Note that client configuration can mean that several Client PC's are running on a remote LAN, often sharing drives and other resources.

Use the function COPY-FILE-TO-SERVER to transfer a file from the Client PC to the server.

Binary mode

The files are transferred in a Binary mode. This means that each file is transferred exactly 'as is'. However if you intend to transfer a text file between Unix server and Windows client you may need to use the ASCII mode equivalent. See COPY-FILE-TO-CLIENT-ASCII and COPY-FILE-TO-SERVER-ASCII.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy a report spooled as report.txt from the server to the client

IF LINK-OS = "U"

MOVE "/tmp/report.txt " TO LINK-EXTRA-1

ELSE

MOVE "C:\TEMP\REPORT.TXT " TO LINK-EXTRA-1.

MOVE "C:\TEMP\CLIENT\REPORT.TXT" TO LINK-EXTRA-2.

MOVE "F" TO LINK-IMPWSH-DIR.

PERFORM COPY-FILE-TO-CLIENT.

IF LINK-IMPWSH-STA = ZERO

GO TO FILE-COPIED-SUCCESSFULLY.

* Copy a screenset called CUSTOM.RS and any associated

* user-controls to the client

MOVE "CUSTOM" TO LINK-EXTRA-1.

MOVE "S" TO LINK-IMPWSH-DIR.

PERFORM COPY-FILE-TO-CLIENT.

IF LINK-IMPWSH-STA = ZERO

GO TO SCREENSET-COPIED-SUCCESSFULLY.

* Copy a report spooled as report.txt from the server to a

* temporary file name on the client returning the new

* client file name

MOVE "report.txt" TO LINK-EXTRA-1.

MOVE "T" TO LINK-IMPWSH-DIR.

PERFORM COPY-FILE-TO-CLIENT.

IF LINK-IMPWSH-STA = ZERO

MOVE LINK-EXTRA-2 TO CLIENT-FILE-NAME

GO TO PROCESS-CLIENT-FILE-NAME.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file names, COPY-FILE-TO-SERVER, COPY-FILE-TO-CLIENT-ASCII, COPY-FILE-TO-SERVER-ASCII, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSXFER


COPY-FILE-TO-CLIENT-ASCII

The COPY-FILE-TO-CLIENT-ASCII function is used to transfer a file from the server system to the client PC using an ASCII mode transfer.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Input parameters

LINK-EXTRA-1

This is the source file to be copied. It must be quoted if spacey.

LINK-EXTRA-2

This is the target file to be copied. It must be quoted if spacey (see LINK-IMPWSH-DIR)

LINK-IMPWSH-DIR

This is a flag indicating the target location on the Client PC.

T | a temporary client file name will be generated. See Output parameters
B | the file will be transferred to the BASE directory
I | the file will be transferred to the BASE\BIN directory
F | LINK-EXTRA-2 contains the full path for the target file

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to copy the file.

Zero – Yes

5 - The ASCII file is over 60,000 bytes (see remarks below)

LINK-EXTRA-2

If the function T was defined in LINK-IMPWSH-DIR this contains the full path name of the temporary file generated on the client.

Remarks

If the required file names are spacey file names then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function is designed to be used to transfer text files from a Server to a Client. On a Unix Server environment the text file on the Server will be transferred to the Client by translating each linefeed to a carriage-return/linefeed pair.

On a Windows Server environment this translation is not required so this function will automatically perform the Binary mode copy function COPY-FILE-TO-CLIENT.

Important: prior to SYSPRO 6.0 issue 010 this function handled a maximum file size of 60,000 bytes. From issue 010 onwards there is no limit to the file size that can be transferred using this function.

Also note that when using Net Express any characters written to a text/ASCII file less than a space (such as Tab, CR, LF etc) will have a NULL character (X"00") inserted immediately before the special character. This file transfer utility will not translate characters that are immediately preceded by a NULL character therefore retaining the same content.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy a text file version.txt from the server to the client

IF LINK-OS = "U"

MOVE "/tmp/version.txt " TO LINK-EXTRA-1

ELSE

MOVE "C:\TEMP\VERSION.TXT " TO LINK-EXTRA-1.

MOVE "C:\TEMP\CLIENT\VERSION.TXT" TO LINK-EXTRA-2.

MOVE "F" TO LINK-IMPWSH-DIR.

PERFORM COPY-FILE-TO-CLIENT-ASCII.

IF LINK-IMPWSH-STA = ZERO

GO TO FILE-COPIED-SUCCESSFULLY.

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 03 and later. Unlimited file size transfer included in SYSPRO 6.0 issue 010.

Copybooks: standard

See also

spacey file names, COPY-FILE-TO-CLIENT, COPY-FILE-TO-SERVER, COPY-FILE-TO-SERVER-ASCII, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSXFER


COPY-FILE-TO-SERVER

The COPY-FILE-TO-SERVER function is used to transfer a file from the client PC to the server system.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Input parameters

LINK-EXTRA-1

This is the source file to be copied. It must be quoted if spacey.

LINK-EXTRA-2

This is the target file to be copied. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to copy the file.

Zero – Yes

Remarks

If the required file names are spacey file names then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function works by reading and transferring blocks of up to 60,000 bytes at a time across the network, reconstructing the target file on the server system. Therefore files up to 60,000 bytes in size are transferred with a single network transition and will be fast. Files requiring relatively few network transitions will also be relatively fast. Large files (half a megabyte or more?) may take a noticeable time to be transferred depending on the network speed.

Note that this function does not use any operating system commands and does not use ftp. The copy is a binary transfer therefore text files may or may not be accessible depending on the target operating system.

Use the function COPY-FILE-TO-CLIENT to transfer a file from the server to a Client PC.

Binary mode

The files are transferred in a Binary mode. This means that each file is transferred exactly 'as is'. However if you intend to transfer a text file between Unix server and Windows client you may need to use the ASCII mode equivalent. See COPY-FILE-TO-CLIENT-ASCII and COPY-FILE-TO-SERVER-ASCII.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy a client file from the client to the server

MOVE "C:\TEMP\CLIENT.TXT" TO LINK-EXTRA-1.

IF LINK-OS = "U"

MOVE "/tmp/server.txt " TO LINK-EXTRA-2

ELSE

MOVE "C:\TEMP\SERVER.TXT " TO LINK-EXTRA-2.

PERFORM COPY-FILE-TO-SERVER.

IF LINK-IMPWSH-STA = ZERO

GO TO FILE-COPIED-SUCCESSFULLY.

Requirements

Version: Included in SYSPRO 6.0 issue 006 and later.

Copybooks: standard

See also

spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, COPY-FILE-TO-CLIENT, COPY-FILE-TO-CLIENT-ASCII, COPY-FILE-TO-SERVER-ASCII, S-OSXFERS


COPY-FILE-TO-SERVER-ASCII

The COPY-FILE-TO-SERVER-ASCII function is used to transfer a file from the client PC to the server system using an ASCII mode transfer.

This command must only be used in a client/server environment.

When running on a slow network connection – such as over a WAN – this function may take a noticeable time as it transfers the file across the network.

Care must be taken to ensure that appropriate files are not overwritten.

Input parameters

LINK-EXTRA-1

This is the source file to be copied. It must be quoted if spacey.

LINK-EXTRA-2

This is the target file to be copied. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to copy the file.

Zero – Yes

5 - The ASCII file is over 60,000 bytes (see remarks below)

Remarks

If the required file names are spacey file names then they must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

This function is designed to be used to transfer text files from a Client to a Server. On a Unix Server environment the text file on the Client will be transferred to the Server by translating each carriage-return/linefeed pair to a single linefeed.

On a Windows Server environment this translation is not required so this function will automatically perform the Binary mode copy function COPY-FILE-TO-SERVER.

Important: prior to SYSPRO 6.0 issue 010 SP1 port 18 (Oct 2007) this function handled a maximum file size of 60,000 bytes. From this version onwards there is no limit to the file size that can be transferred using this function.

Also note that when using Net Express any characters written to a text/ASCII file less than a space (such as Tab, CR, LF etc) will have a NULL character (X"00") inserted immediately before the special character. This file transfer utility will not translate characters that are immediately preceded by a NULL character therefore retaining the same content.

The sample program SDKWSH supplied as part of the Software Development Kit demonstrates use of this and other file copy/transfer functions.

Sample code

* Copy a client file from the client to the server

MOVE "C:\TEMP\CLIENT.TXT" TO LINK-EXTRA-1.

IF LINK-OS = "U"

MOVE "/tmp/server.txt " TO LINK-EXTRA-2

ELSE

MOVE "C:\TEMP\SERVER.TXT " TO LINK-EXTRA-2.

PERFORM COPY-FILE-TO-SERVER-ASCII.

IF LINK-IMPWSH-STA = ZERO

GO TO FILE-COPIED-SUCCESSFULLY.

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 03 and later. Unlimited file size transfer included in SYSPRO 6.0 issue 010 SP1 Port 18.

Copybooks: standard

See also

spacey file names, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, COPY-FILE-TO-SERVER, COPY-FILE-TO-CLIENT, COPY-FILE-TO-CLIENT-ASCII, S-OSXFERS


CREATE-DIRECTORY-ON-CLIENT

The CREATE-DIRECTORY-ON-CLIENT function is used to create a folder on the client PC. It's parent must already exist and you must have appropriate permission.

If this command is used on a standalone/mapped system then this function is identical to CREATE-DIRECTORY-ON-SERVER.

Input parameters

LINK-EXTRA-1

This is the directory to be created. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to create the directory.

Zero – Yes

Remarks

If the required folder contains spaces then it must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

You are responsible for ensuring that the parent folder already exists and that you have permission to create the folder required.

There is an equivalent function called CREATE-DIRECTORY-ON-SERVER.

Sample code

* Create C:\TEMP\CLIENT folder on client

MOVE "C:\TEMP\CLIENT" TO LINK-EXTRA-1.

PERFORM CREATE-DIRECTORY-ON-CLIENT.

IF LINK-IMPWSH-STA = ZERO

GO TO FOLDER-COPIED-SUCCESSFULLY.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

spacey file names, COPY-FILE-TO-SERVER, COPY-FILE-TO-CLIENT-ASCII, COPY-FILE-TO-SERVER-ASCII, CREATE-DIRECTORY-ON-SERVER, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME


CREATE-DIRECTORY-ON-SERVER

The CREATE-DIRECTORY-ON-SERVER function is used to create a folder on the server. It's parent must already exist and you must have appropriate permission.

If this command is used on a standalone/mapped system then this function is identical to CREATE-DIRECTORY-ON-CLIENT.

Input parameters

LINK-EXTRA-1

This is the directory to be created. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to create the directory.

Zero – Yes

Remarks

If the required folder contains spaces then it must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

You are responsible for ensuring that the parent folder already exists and that you have permission to create the folder required.

Remember that on a Unix based system you must use forward slashes and that spacey file names are not supported.

There is an equivalent function called CREATE-DIRECTORY-ON-CLIENT.

Sample code

* Create C:\TEMP\SERVER folder on client

IF LINK-OS = "U"

MOVE "/tmp/server" TO LINK-EXTRA-1

ELSE

MOVE "C:\TEMP\SERVER" TO LINK-EXTRA-1

END-IF.

PERFORM CREATE-DIRECTORY-ON-SERVER.

IF LINK-IMPWSH-STA = ZERO

GO TO FOLDER-COPIED-SUCCESSFULLY.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

spacey file names, COPY-FILE-TO-SERVER, COPY-FILE-TO-CLIENT-ASCII, COPY-FILE-TO-SERVER-ASCII, CREATE-DIRECTORY-ON-CLIENT, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME


CUSTOM-FORM-COPY

The CUSTOM-FORM-COPY function is designed to allow Custom form data for an existing key to be copied to another key of the same form type. For example if your program is copying a stock code you may want to copy any Custom form data as well.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the existing key of the Custom form to be copied. For example for form type STK this is the existing stock code.

LINK-CUST-KEY2

This is the new (target) key. For example the new stock code.

Output parameters

none

Remarks

This function is used when a key field is being duplicated/copied and allows any existing custom form data to be duplicated/copied.

Most of the Custom forms functions can be accessed directly from a screenset using the S-FORM functions.

Sample code

* Copy Custom form for a stock code

MOVE "STK" TO LINK-CUST-TYPE. *> Stock codes

MOVE D-OLD-STOCK-CODE TO LINK-CUST-KEY.

MOVE D-NEW-STOCK-CODE TO LINK-CUST-KEY2.

PERFORM CUSTOM-FORM-COPY.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-EDIT, CUSTOM-FORM-GET, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST


CUSTOM-FORM-COPY-TYPE

The CUSTOM-FORM-COPY-TYPE function is designed to allow Custom form data for an existing key to be copied to another key of a different form type. For example if your program is creating an invoice from a sales order you could copy all the Custom form fields for a sales order to the invoice.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character source form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the existing key of the Custom form to be copied. For example for form type STK this is the existing stock code.

LINK-CUST-TYPE2

This is the new (target) form type.

LINK-CUST-KEY2

This is the new (target) key. For example the new stock code.

Output parameters

none

Remarks

This function is easiest explained with an example.

Suppose you have a Custom form defined against a sales order. This could contain several form fields. When your application generates an invoice you may wish to transfer all relevant form fields from the original sales order to the newly created invoice.

This is done by moving ORD to LINK-CUST-TYPE and the sales order number to LINK-CUST-KEY.

Then you should move INV to LINK-CUST-TYPE2 and the invoice number to LINK-CUST-KEY2.

The perform CUSTOM-FORM-COPY-TYPE. This will identify all the form fields with the same name in both form definitions and will copy the form data.

It is important to ensure that the form fields to be transferred have exactly the same name for this function to work. By using fields of different names it is possible to deliberately not transfer certain information – for example information that was only relevant to the sales order and not the invoice.

Most of the Custom forms functions can be accessed directly from a screenset using the S-FORM functions.

Sample code

* Copy Custom form for sales order to an invoice

MOVE "ORD" TO LINK-CUST-TYPE. *> Sales order

MOVE D-SALES-ORDER TO LINK-CUST-KEY.

MOVE "INV" TO LINK-CUST-TYPE2. *> Invoice

MOVE D-INVOICE TO LINK-CUST-KEY2.

PERFORM CUSTOM-FORM-COPY-TYPE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-EDIT, CUSTOM-FORM-GET, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST


CUSTOM-FORM-DEL

The CUSTOM-FORM-DEL function is designed to allow a Custom form for a specific key to be deleted.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the key of the Custom form to be deleted. For example for form type STK this is the stock code.

Output parameters

none

Remarks

This function should be used to delete an existing Custom form against a key field whenever a key field is deleted. Failure to do this may result in the key field being re-used and the Custom form data appearing against this new field.

Most of the Custom forms functions can be accessed directly from a screenset using the S-FORM functions.

Sample code

* Delete a Custom form for a stock code

MOVE "STK" TO LINK-CUST-TYPE. *> Stock codes

MOVE D-STOCK-CODE TO LINK-CUST-KEY.

PERFORM CUSTOM-FORM-DEL.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-EDIT, CUSTOM-FORM-GET, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-TEST


CUSTOM-FORM-EDIT

The CUSTOM-FORM-EDIT function is designed to allow the operator to enter new data onto a Custom form. If the form already exists then the existing data will be shown and the operator may amend it. If the form does not exist then a new one will be created with default values.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the key of the Custom form to be edited. For example for form type STK this is the stock code.

Output parameters

none

Remarks

This function is used to allow the operator to add or amend a Custom form.

See the Custom forms subject for details about how to add your own type of forms.

Most of the Custom form functions can be accessed directly from a screenset using the S-FORM functions.

Sample code

* Edit a Custom form for a stock code

MOVE "STK" TO LINK-CUST-TYPE. *> Stock codes

MOVE D-STOCK-CODE TO LINK-CUST-KEY.

PERFORM CUSTOM-FORM-EDIT.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-GET, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST


CUSTOM-FORM-GET

The CUSTOM-FORM-GET function is designed to retrieve a single field from a Custom form.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the existing key of the Custom form to be retrieved. For example for form type STK this is the existing stock code.

LINK-CUST-NAME

This is the 6 character name of the custom form field to be retrieved.

Output parameters

LINK-CUST-DATA

This is the returned value of the custom form field. See the field LINK-CUST-AND for a flag indicating whether the field is alpha, numeric or date.

For numeric form fields this field contains an edited numeric value.

For date form fields this field contains an edited date.

LINK-CUST-DATA-N

If the field is numeric then this field contains the numeric value.

LINK-CUST-DATA-D

If the field is a date then this field contains the date in CCYYMMDD format.

LINK-CUST-AND

This is a flag indicating the returned field type:

A – Alphanumeric

N – Numeric

D – Date

LINK-CUST-STAT

A status indicator.

Spaces - OK

Remarks

This function is used to retrieve a single form value from a custom form.

Most of the Custom forms functions can be accessed directly from a screenset using the S-FORM functions.

Sample code

* Retrieve a form field called 'custom' from a stock code

MOVE "STK" TO LINK-CUST-TYPE. *> Stock code

MOVE "custom" TO LINK-CUST-NAME.

MOVE D-STOCK-CODE TO LINK-CUST-KEY.

PERFORM CUSTOM-FORM-GET.

IF LINK-CUST-STAT = SPACES

EVALUATE LINK-CUST-AND

WHEN "A" MOVE LINK-CUST-DATA TO ALPHA-VALUE

WHEN "N" MOVE LINK-CUST-DATA-N TO NUMERIC-VALUE

WHEN "D" MOVE LINK-CUST-DATA-D TO DATE-VALUE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-EDIT, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST


CUSTOM-FORM-READ-ALL

The CUSTOM-FORM-READ-ALL function is designed to retrieve all the form fields for a key.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the existing key of the Custom form to be retrieved. For example for form type STK this is the existing stock code.

Output parameters

LINK2

The field LINK2 will return a block of information defined in the copybook IMPFRM.LNK. This is a list of up to 100 custom form fields.

Remarks

This function is used to retrieve all the form fields against a single key.

The format of the information is defined in the copybook IMPFRM.LNK. The first field defines the number of returned form fields.

Most of the Custom forms functions can be accessed directly from a screenset using the S-FORM functions. However this function must be called from a Net Express program.

Note there is a similar function called CUSTOM-FORM-READ-ALL-DESC that returns just the field description and the edited alpha value.

Sample code

* Retrieve all form fields from a stock code

MOVE "STK" TO LINK-CUST-TYPE. *> Stock code

MOVE D-STOCK-CODE TO LINK-CUST-KEY.

PERFORM CUSTOM-FORM-READ-ALL.

IF IMPFRM-COUNT > ZERO

MOVE 1 TO XX1

PERFORM EXTRACT-DATA IMPFRM-COUNT TIMES.

*

EXTRACT-DATA.

MOVE IMPFRM-NAM(XX1) TO FORM-NAME(XX1).

MOVE IMPFRM-AND(XX1) TO FORM-AND(XX1).

EVALUATE IMPFRM-AND(XX1)

WHEN "A" MOVE IMPFRM-ALP(XX1) TO FORM-ALP-VALUE(XX1)

WHEN "N" MOVE IMPFRM-NUM(XX1) TO FORM-NUM-VALUE(XX1)

WHEN "D" MOVE IMPFRM-DAT(XX1) TO FORM-DAT-VALUE(XX1).

ADD 1 TO XX1.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-EDIT, CUSTOM-FORM-GET, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST, CUSTOM-FORM-READ-ALL-DESC


CUSTOM-FORM-READ-ALL-DESC

The CUSTOM-FORM-READ-ALL-DESC function is designed to retrieve all the form fields for a key.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the existing key of the Custom form to be retrieved. For example for form type STK this is the existing stock code.

Output parameters

LINK2 (IMPFRM2-TAB)

The field LINK2 will return a block of information defined in the copybook IMPFRM.LNK. This is a list of up to 100 custom form fields and their descriptions.

Remarks

This function is used to retrieve all the form fields against a single key.

The format of the information is defined in the copybook IMPFRM.LNK. The first field defines the number of returned form fields.

Most of the Custom forms functions can be accessed directly from a screenset using the S-FORM functions. However this function must be called from a Net Express program.

Note there is a similar function called CUSTOM-FORM-READ-ALL that returns the field definitions and field name together with the edited alpha value and the raw numeric/date values.

Sample code

* Retrieve all form fields from a stock code

MOVE "STK" TO LINK-CUST-TYPE. *> Stock code

MOVE D-STOCK-CODE TO LINK-CUST-KEY.

PERFORM CUSTOM-FORM-READ-ALL-DESC.

IF IMPFRM-COUNT > ZERO

MOVE 1 TO XX1

PERFORM EXTRACT-DATA IMPFRM-COUNT TIMES.

*

EXTRACT-DATA.

MOVE IMPFRM2-DESC(XX1) TO FORM-DESC(XX1).

MOVE IMPFRM2-ALP(XX1) TO FORM-ALP(XX1).

ADD 1 TO XX1.

Requirements

Version: Included in SYSPRO 6.0 Issue 010 SP1 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-EDIT, CUSTOM-FORM-GET, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST, CUSTOM-FORM-READ-ALL


CUSTOM-FORM-READ-CTL

The CUSTOM-FORM-READ-CTL function is designed to retrieve all the form fields names for a form type. This can be used to retrieve a list of the custom form fields configured against a single custom form type. This does not return any data against a specific key – just the fields names and the alpha, numeric or date indicator.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

Output parameters

LINK2

The field LINK2 will return a block of information defined in the copybook IMPFRM.LNK. This is a list of up to 50 custom form fields.

Remarks

This function is used to extract all the form fields against a form type.

For example if you want to print all custom form fields against a sales order the you can use this function to retrieve a list of the form fields and allow the user to define a print position for each field.

The format of the information is defined in the copybook IMPFRM.LNK. The first field defines the number of returned form fields.

Most of the Custom forms functions can be accessed directly from a screenset using the S-FORM functions.

Sample code

* Retrieve all form fields defined against a sales order

MOVE "ORD" TO LINK-CUST-TYPE. *> Sales order

PERFORM CUSTOM-FORM-READ-CTL.

IF IMPFRM-COUNT > ZERO

MOVE 1 TO XX1

PERFORM EXTRACT-NAMES IMPFRM-COUNT TIMES.

*

EXTRACT-DATA.

MOVE IMPFRM-NAM(XX1) TO FORM-NAME(XX1).

MOVE IMPFRM-AND(XX1) TO FORM-AND(XX1).

ADD 1 TO XX1.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-EDIT, CUSTOM-FORM-GET, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-TEST


CUSTOM-FORM-TEST

The CUSTOM-FORM-TEST function is designed to allow a program to determine whether a custom form with mandatory fields has been successfully added.

Typically this is used by maintenance programs so that they can verify that a custom form has been added.

Custom forms are a flexible and consistent way of allowing an administrator to configure additional information against a key field that would not normally be captured within SYSPRO. Developers can define custom forms against any field.

Input parameters

LINK-CUST-TYPE

This is a 6 character form type indicating the type of Custom form. Existing standard custom form types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Custom forms should use form types beginning with USR.

LINK-CUST-KEY

This is the key of the Custom form to be tested. For example for form type STK this is the stock code.

Output parameters

LINK-CUST-STAT

This fields returns the status of the test.

Blank indicates that either there are no mandatory fields for this form or that all the mandatory fields have been defined for this key field.

Non-blank indicates that one or more mandatory fields have not yet been defined for the key field.

Remarks

This function is typically used by a maintenance program so that when adding a new item the maintenance program can ensure that a custom form with mandatory fields has been captured.

A mandatory field means a field that is set as not 'allowing spaces in field' or not 'allowing zeroes in field'.

See the Custom forms subject for details about how to add your own type of forms.

Most of the Custom form functions can be accessed directly from a screenset using the S-FORM functions.

Sample code

* Test if mandatory form fields have been captured

TEST-FOR-MANDATORY-FIELDS.

MOVE "STK" TO LINK-CUST-TYPE. *> Stock codes

MOVE D-STOCK-CODE TO LINK-CUST-KEY.

PERFORM CUSTOM-FORM-TEST.

IF LINK-CUST-STAT = SPACES

PERFORM OK-TO-ADD-ITEM

ELSE

PERFORM LOAD-CUSTOM-FORM-FOR-EDITING

GO TO TEST-FOR-MANDATORY-FIELDS.

Requirements

Version: Included in SYSPRO 6.0 Issue 006 and later.

Copybooks: standard

See also

Custom forms, CUSTOM-FORM-GET, CUSTOM-FORM-READ-ALL, CUSTOM-FORM-READ-CTL, CUSTOM-FORM-COPY, CUSTOM-FORM-COPY-TYPE, CUSTOM-FORM-DEL, CUSTOM-FORM-EDIT


DATE-COMPARE

The DATE-COMPARE function is used to compare two dates stored in the SYSPRO standard date format.

Input parameters

DD-LDAT

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

DD-HDAT

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

Output parameters

DD-LDAT-EARLIER

A flag indicating that DD-LDAT is earlier than DD-HDAT.

Y – Yes

DD-LDAT-LATER

A flag indicating that DD-LDAT is later than DD-HDAT.

Y – Yes

DD-HDAT-EARLIER

A flag indicating that DD-HDAT is earlier than DD-LDAT.

Y – Yes

DD-HDAT-LATER

A flag indicating that DD-HDAT is later than DD-LDAT.

Y – Yes

BOTH-DATES-EQUAL

A flag indicating that DD-LDAT is the same as DD-HDAT.

Y – Yes

ANS

A flag indicating that DD-LDAT is after DD-HDAT. This is for compatibility with older versions of this routine. It is recommended to use one of the other returned fields.

N - No

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

This routine is used to compare dates stored in this format.

Note that dates stored in this format can be in the range:

1st Jan 1950 through 31st Jan 2049

Dates stored in a file or a SYSPRO database are always defined as CCYYMMDD format regardless of the setting described above. To swap between these date formats use DATE-TO-CYMD and DATE-FROM-CYMD.

To swap dates from the 6 digit SYSPRO standard date format and a YYMMDD format use DATE-YMD and DATE-NORM.

Sample code

MOVE D-FROM-DATE TO DD-LDAT.

MOVE D-TO-DATE TO DD-HDAT.

PERFORM DATE-COMPARE.

IF DD-LDAT-EARLIER = "Y"

GO TO D-FROM-DATE-IS-EARLIER.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-TO-CYMD, DATE-FROM-CYMD, DATE-YMD, DATE-NORM, Date ageing functions


DATE-COMPARE-YMD

The DATE-COMPARE-YMD function is used to compare two dates stored in YYMMDD date format.

Input parameters

DD-LDAT

A 6 digit date stored in YYMMDD date format.

DD-HDAT

A 6 digit date in YYMMDD date format.

Output parameters

DD-LDAT-EARLIER

A flag indicating that DD-LDAT is earlier than DD-HDAT.

Y – Yes

DD-LDAT-LATER

A flag indicating that DD-LDAT is later than DD-HDAT.

Y – Yes

DD-HDAT-EARLIER

A flag indicating that DD-HDAT is earlier than DD-LDAT.

Y – Yes

DD-HDAT-LATER

A flag indicating that DD-HDAT is later than DD-LDAT.

Y – Yes

BOTH-DATES-EQUAL

A flag indicating that DD-LDAT is the same as DD-HDAT.

Y – Yes

ANS

A flag indicating that DD-LDAT is after DD-HDAT. This is for compatibility with older versions of this routine. It is recommended to use one of the other returned fields.

N - No

Remarks

This routine is used to compare dates stored in YYMMDD date format.

Note that dates stored in this format can be in the range:

1st Jan 1950 through 31st Jan 2049

Dates requested from the screen are stored in a SYSPRO standard date format. To swap these dates to/from the YYMMDD date format use DATE-YMD and DATE-NORM.

Sample code

MOVE D-FROM-YYMMDD TO DD-LDAT.

MOVE D-TO-YYMMDD TO DD-HDAT.

PERFORM DATE-COMPARE-YMD.

IF DD-LDAT-EARLIER = "Y"

GO TO D-FROM-YYMMDD-IS-EARLIER.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-YMD, DATE-NORM, Date ageing functions


DATE-FROM-CYMD

The DATE-FROM-CYMD function is used to swap a date in CCYYMMDD format to a date in the SYSPRO standard date format.

Input parameters

DATE-CCYYMMDD

An 8 digit date in CCYYMMDD format.

Output parameters

DATE-NORMAL

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

This routine is used to swap a date in CCYYMMDD format to dates in the SYSPRO standard date format.

Note that dates stored in this format can be in the range:

1st Jan 1950 through 31st Jan 2049

To swap dates back from the SYSPRO standard date format to CCYYMMDD format use DATE-TO-CYMD.

Sample code

MOVE DATE-IN-CCYYMMDD-FORMAT TO DATE-YYMMDD.

PERFORM DATE-FROM-CYMD.

MOVE DATE-NORMAL TO D-ASK-DATE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-TO-CYMD, Date ageing functions


DATE-NORM

The DATE-NORM function is used to swap a date in YYMMDD format to a date in the SYSPRO standard date format.

Input parameters

DATE-YYMMDD

A 6 digit date in YYMMDD format.

Output parameters

DATE-NORMAL

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

This routine is used to swap a date in YYMMDD format to dates in the SYSPRO standard date format.

Note that dates stored in this format can be in the range:

1st Jan 1950 through 31st Jan 2049

To swap dates from the SYSPRO standard date format to YYMMDD format use DATE-YMD.

Sample code

MOVE DATE-IN-YYMMDD-FORMAT TO DATE-YYMMDD.

PERFORM DATE-NORM.

MOVE DATE-NORMAL TO D-ASK-DATE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-YMD, Date ageing functions


DATE-TO-CYMD

The DATE-TO-CYMD function is used to swap a date in the SYSPRO standard date format to CCYYMMDD format.

Input parameters

DATE-NORMAL

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

Output parameters

DATE-CCYYMMDD

An 8 digit date in CCYYMMDD format.

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

This routine is used to swap a date in this format to CCYYMMDD.

Note that dates stored in this format can be in the range:

1st Jan 1950 through 31st Jan 2049

Dates stored in a file or a SYSPRO database are always defined as CCYYMMDD format regardless of the setting described above. To swap a CCYYMMDD date to the SYSPRO standard date format use DATE-FROM-CYMD.

Sample code

MOVE D-ASK-DATE TO DATE-NORMAL.

PERFORM DATE-TO-CYMD.

MOVE DATE-CCYYMMDD TO DATE-IN-CCYYMMDD-FORMAT.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-FROM-CYMD, Date ageing functions


DATE-YMD

The DATE-YMD function is used to swap a date in the SYSPRO standard date format to YYMMDD format.

Input parameters

DATE-NORMAL

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

Output parameters

DATE-YYMMDD

A 6 digit date in YYMMDD format.

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

This routine is used to swap a date in this format to YYMMDD.

Note that dates stored in this format can be in the range:

1st Jan 1950 through 31st Jan 2049

Dates stored in a file or a SYSPRO database are always defined as CCYYMMDD format regardless of the setting described above. To swap between these date formats use DATE-TO-CYMD and DATE-FROM-CYMD.

To swap dates from the YYMMDD date format to the standard date format use DATE-NORM.

Sample code

MOVE D-ASK-DATE TO DATE-NORMAL.

PERFORM DATE-YMD.

MOVE DATE-YYMMDD TO DATE-IN-YYMMDD-FORMAT.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-TO-CYMD, DATE-FROM-CYMD, DATE-NORM, Date ageing functions


DECREMENT-LINE-X5

The DECREMENT-LINE-X5 function is used decrement a 5 character alphanumeric line number.

This function is used in the General Ledger module where a 5 character alphanumeric line number has been used.

Input parameters

WW-LINE-X5

The initial value of the line number to be decremented.

May be '00000' - '99999' or 'AAAAA' - 'ZZZZZ'.

Output parameters

WW-LINE-X5

This field returns the initial value decremented by 1. See the Remarks for valid values.

WW-LINE-STAT

This field returns status information about the increment function.

Spaces - OK

O - Field overflow (reached '00000')

E - Invalid initial value

Remarks

This function is used by various General Ledger programs to manipulate an alphanumeric line number.

Background

The General Ledger system had 5 digit line numbers defined in various files. The line numbers were therefore limited to the values '00000' - '99999' (100,000 values).

An increase in the number of values was required but due to ISAM space limitations the 5 digit numeric line number has been changed to a 5 character alphanumeric line number for SYSPRO 6.0 issue 008.

The valid values are '00000' - '99999' (as before) plus 'AAAAA' - 'ZZZZZ'. This gives an additional 11,881,376 values. Therefore the total number of available line numbers is 11,981,376 (or approximately 12 million).

The new functions

Two new functions have been developed to allow developers to increment and decrement the 5 character alphanumeric line numbers. These are INCREMENT-LINE-X5 and DECREMENT-LINE-X5.

These new routines take the field WW-LINE-X5 and either increment or decrement the value according to the following logic:

- The valid values are '00000' - '99999' and 'AAAAA' - 'ZZZZZ'.

- When incrementing a value '00000' it will become '00001', then '00002', then '00003' etc.

- When incrementing a value '99999' it will become 'AAAAA'.

- Incrementing a value 'AAAAA' will return 'AAAAB', then 'AAAAC' etc.

- When incrementing 'ZZZZZ' you will receive an overflow error value 'O' in WW-LINE-STAT.

- If you pass a value outside the valid range you will receive an error value 'E' in WW-LINE-STAT.

- An initial value of spaces will be assumed to be '00000'.

The reverse logic is used when decrementing:

- 'ZZZZZ' will become 'ZZZZY', 'ZZZZY' will become 'ZZZZX' etc.

- 'AAAAA' will become '99999'.

- Decrementing '00000' will return the overflow (underflow) value 'O' in WW-LINE-STAT.

Remember when using these fields to store them as PIC X(5) - char(5) and also you should use care when displaying/printing these fields as they are alphanumeric fields.

Sample code

* Decement a G/L line number

MOVE GENTRN-LIN TO WW-LINE-X5.

PERFORM DECREMENT-LINE-X5.

IF WW-LINE-STAT = "O"

PERFORM MIN-LINE-NUMBER-EXCEEDED

ELSE

IF WW-LINE-STAT = "E"

PERFORM INVALID-LINE-NUMBER

ELSE

MOVE WW-LINE-X5 TO GENTRN-LIN.

Requirements

Version: Included in SYSPRO 6.0 issue 008 and later

Copybooks: standard

See also

INCREMENT-LINE-X5


DECRYPT-CIPHER-TEXT

The DECRYPT-CIPHER-TEXT function is designed to decode text encoded with the ENCRYPT-PLAIN-TEXT function. See this function for more details.

Input parameters

LINK-SEED-TEXT

This is a 50 character string that was originally used to scramble your plain text.

LINK-CIPHER-TEXT

This is the string that was generated by the ENCRYPT-PLAIN-TEXT function.

LINK-CIPHER-SUM

This is the checksum that was generated by the ENCRYPT-PLAIN-TEXT function.

Output parameters

LINK-PLAIN-TEXT

This is the returned plain text.

Remarks

See the description of the ENCRYPT-PLAIN-TEXT function for more details.

Sample code

* Encrypt a password for later use

ENCRYPT-PASS.

MOVE "AbSD2ZJq0W8hPf61" TO LINK-SEED-TEXT. *> Seed

MOVE D-ENTERED-PASSWORD TO LINK-PLAIN-TEXT.

PERFORM ENCRYPT-PLAIN-TEXT.

MOVE LINK-CIPHER-TEXT TO SAVED-ENCRYPTED-TEXT.

MOVE LINK-CIPHER-SUM TO SAVED-ENCRYPTED-CHECKSUM.

* Decrypt password from saved fields

DECRYPT-PASS.

MOVE "AbSD2ZJq0W8hPf61" TO LINK-SEED-TEXT. *> Seed

MOVE SAVED-ENCRYPTED-TEXT TO LINK-CIPHER-TEXT.

MOVE SAVED-ENCRYPTED-CHECKSUM TO LINK-CIPHER-SUM.

PERFORM DECRYPT-CIPHER-TEXT.

MOVE LINK-PLAIN-TEXT TO ORIGINAL-PASSWORD.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

ENCRYPT-PLAIN-TEXT


DEL-FILE-ON-CLIENT

The DEL-FILE-ON-CLIENT function is used to delete a file on the client PC.

In a Client/Server environment this will be issued on the Client PC. This will always be a Windows environment.

Care must be taken to ensure that only appropriate files are deleted.

Input parameters

LINK-EXTRA-1

This is the required file to be deleted from the Client PC. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to delete the file.

Zero - Yes

Remarks

If the required file name is a spacey file name then it must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

In a client/server system the command is executed on the client PC.

In a mapped drive system the command is executed on the client PC.

Sample code

* Delete a file from the client

MOVE "C:\TEMP\REPORT.TXT" TO LINK-EXTRA-1.

PERFORM DEL-FILE-ON-CLIENT.

IF LINK-IMPWSH-STA = ZERO

GO TO FILE-DELETED-SUCCESSFULLY.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file name, DEL-FILE-ON-SERVER, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSDEL


DEL-FILE-ON-SERVER

The DEL-FILE-ON-SERVER function is used to delete a file on the server.

In a Client/Server environment this will be issued on the server. This may be a Windows or Unix system.

Care must be taken to ensure that appropriate files are deleted.

Input parameters

LINK-EXTRA-1

This is the required file to be deleted from the server. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to delete the file.

Zero - Yes

Remarks

If the required file name is a spacey file name then it must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

In a client/server system the command is executed on the server.

In a mapped drive system the command is executed on the client PC.

Sample code

* Delete a file from the server

IF LINK-OS = "U"

MOVE "/tmp/report.txt" TO LINK-EXTRA-1

ELSE

MOVE "C:\TEMP\REPORT.TXT" TO LINK-EXTRA-1.

PERFORM DEL-FILE-ON-SERVER.

IF LINK-IMPWSH-STA = ZERO

GO TO FILE-DELETED-SUCCESSFULLY.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file name, DEL-FILE-ON-CLIENT, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSDELS


DEL-PASSWORD

The DEL-PASSWORD function is used to delete an existing password. This should be used when an item is deleted to ensure that the old password is removed.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being deleted.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required. Note that for the operator file this will be blank.

LINK-PASS-KEY

This is the key of the item being deleted.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – for example a credit note – then you could use the phrase 'credit note' as the key. This will form part of the encryption key so a longer phrase is better than a short one.

Output parameters

none

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The DEL-PASSWORD function should be issued whenever an item that has a password is deleted. If this is not done consider the following:

  • An item is added

  • A password is defined against this item

  • The item is deleted but the password is not deleted

  • Some time later an item with the same code is added

  • The previously defined password will be active!

Sample code

* Delete my password for a stock code

MOVE "USRSTK" TO LINK-PASS-TYP. *> 'USRSTK' password

MOVE COMPID TO LINK-PASS-CMP. *> Company specific

MOVE INVMST-STK TO LINK-PASS-KEY. *> stock code

PERFORM DEL-PASSWORD.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-OLD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL


DELETE-AP-PAY-LOCK-FILE

The DELETE-AP-LOCK-FILE function is used to remove all locks previously acquired to process the A/P Payments Release file.

It is important to acquire a lock for a supplier before processing the A/P Payment Release information for the supplier. See the GET-AP-PAY-LOCK function.

Input parameters

none

Output parameters

none

Remarks

Use this function to delete all locks for A/P Payment releases for a suppliers.

Sample code

* Remove all A/P Payment release locks

PERFORM DELETE-AP-PAY-LOCK-FILE.

Requirements

Version: Included in Encore 5.1 issue 004 and later.

Copybooks: standard

See also

GET-AP-PAY-LOCK, CLEAR-AP-PAY-LOCK


DELETE-WW-FILE-NAME

The DELETE-WW-FILE-NAME function is used to delete a file on the server.

Input parameters

WW-FILE-NAME

The file name to be deleted – must have quotes if a spacey file name

Output parameters

none

Remarks

The name must be quoted if it is a spacey file name. Use QUOTE-VALID-FILE-NAME to quote a spacey file name.

If the file is a data file then it must be closed before it can be deleted.

If you are deleting an indexed file then you need to use the DELETE-INDEX-FILE function that deletes both the data and index portions. See the topic Deleting files for more information and sample code and use of the PRODEL.PRO copybook.

Sample code

MOVE "C:\Syspro\Temp\Report.txt" TO WW-FILE-NAME.

PERFORM DELETE-WW-FILE-NAME.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

Deleting files, spacey file name, QUOTE-VALID-FILE-NAME, PRODEL.PRO


EDIT-DATE-TO-USER-FORMAT

The EDIT-DATE-TO-USER-FORMAT function is used to format a date stored in the SYSPRO standard date format to one of several edit formats. The System setup program can be used to define the Short date, Long date and Report date formats.

Input parameters

DATE-NORMAL

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

WW-DATE-FORMAT

A flag indicating the required date format. One of

- N 99/99/99

- L Long date format

- S Short date format

- R Report date format

Output parameters

WW-EDITED-DATE

A 50 character alphanumeric field containing the edited date.

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

This routine is edit a date in this date format to one of the standard edited formats.

N – 99/99/99

This edited format simply inserts slashes (/) between the digits. No other editing or formatting is performed.

L – Long date format

S – Short date format

R – Report date format

These three formats are defined by an administrator in the System Setup program. Various characters can be used to format a date in very flexible ways. Many standard SYSPRO stationery formats, such as invoices and customer statements can have their dates formatted using one of these three formats.

Standard SYSPRO reports use the Report date format to show the current company date at the top of each report.

Examples of the formatting capability is shown below. All these assume the date to be formatted is 28th April 2005.

Date format | Edited date
dd MMMM yyyy | 28 April 2005
MM/dd/yyyy | 04/28/2005
MM/dd/yyyy HH:mm | 04/28/2005 22:50
'Today is' dddd MMMM d yyyy | Today is Thursday April 28 2005

As most standard SYSPRO reports use the Report date format there is a special routine EDIT-REPORT-DATE for this purpose.

Note that if you wish to specify the format at run-time you should use EDIT-FORMATTED-DATE.

Also note that if you have the date in an 8 digit format you can use EDIT-DATE-TO-USER-FORMAT-CYMD.

Sample code

MOVE D-ASK-DATE TO DATE-NORMAL.

MOVE "L" TO WW-DATE-FORMAT. *> Long date format

PERFORM EDIT-DATE-TO-USER-FORMAT.

MOVE WW-EDITED-DATE TO LONG-DATE-FORMAT.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

EDIT-DATE-TO-USER-FORMAT-CYMD, EDIT-REPORT-DATE, EDIT-FORMATTED-DATE


EDIT-DATE-TO-USER-FORMAT-CYMD

The EDIT-DATE-TO-USER-FORMAT-CYMD function is used to format an 8 digit date stored in CCYYMMDD format to one of several edit formats. The System setup program can be used to define the Short date, Long date and Report date formats.

Input parameters

DATE-CCYYMMDD

An 8 digit date in CCYYMMDD format.

WW-DATE-FORMAT

A flag indicating the required date format. One of

- L Long date format

- S Short date format

- R Report date format

Output parameters

WW-EDITED-DATE

A 50 character alphanumeric field containing the edited date.

Remarks

Dates requested in an entry form or from a file are typically stored in the 8 digit format CCYYMMDD.

This routine is edit a date in this date format to one of the standard edited formats.

L – Long date format

S – Short date format

R – Report date format

These three formats are defined by an administrator in the System Setup program. Various characters can be used to format a date in very flexible ways. Many standard SYSPRO stationery formats, such as invoices and customer statements can have their dates formatted using one of these three formats.

Standard SYSPRO reports use the Report date format to show the current company date at the top of each report.

Examples of the formatting capability is shown below. All these assume the date to be formatted is 28th April 2005.

Date format | Edited date
dd MMMM yyyy | 28 April 2005
MM/dd/yyyy | 04/28/2005
MM/dd/yyyy HH:mm | 04/28/2005 22:50
'Today is' dddd MMMM d yyyy | Today is Thursday April 28 2005

As most standard SYSPRO reports use the Report date format there is a special routine EDIT-REPORT-DATE for this purpose.

Note that if you wish to specify the format at run-time you should use EDIT-FORMATTED-DATE.

Also note that if you have the date in the SYSPRO normal format you can use EDIT-DATE-TO-USER-FORMAT.

Sample code

MOVE CRMCON-DATE-OF-BIRTH TO DATE-CCYYMMDD. *> Date in CCYYMMDD format

MOVE "L" TO WW-DATE-FORMAT. *> Long date format

PERFORM EDIT-DATE-TO-USER-FORMAT-CYMD.

MOVE WW-EDITED-DATE TO LONG-DATE-FORMAT.

Requirements

Version: Included in SYSPRO 6.1 and later

Copybooks: standard

See also

EDIT-DATE-TO-USER-FORMAT, EDIT-REPORT-DATE, EDIT-FORMATTED-DATE


EDIT-DATE-YYYY-MM-DD

The EDIT-DATE-YYYY-MM-DD function is used to format a date stored in CCYYMMDD format to a YYYY-MM-DD format. This is useful if you need to pass a date to SQL Server.

Input parameters

DATE-CCYYMMDD

An 8 digit date stored in CCYYMMDD format

Output parameters

WW-EDITED-DATE

The dated edited as YYYY-MM-DD

Remarks

This function is useful if you try and include a date in a SQL Server WHERE clause.

Note that if you want to return a more flexible date format then use the EDIT-FORMATTED-DATE function - this allows virtually any date format to be specified.

Sample code

MOVE 20050428 TO DATE-CCYYMMDD.

PERFORM EDIT-DATE-YYYY-MM-DD.

MOVE WW-EDITED-DATE TO DATE-IS-YYYY-MM-DD-FORMAT.

Requirements

Version: Included in Encore 5.1 issue 005 and later

Copybooks: standard

See also

EDIT-REPORT-DATE, EDIT-FORMATTED-DATE


EDIT-FORMATTED-DATE

The EDIT-FORMATTED-DATE function is used to format a date stored in CCYYMMDD format to a flexible user-defined format.

Input parameters

DATE-CCYYMMDD

An 8 digit date stored in CCYYMMDD format

WW-TIME

A time in HHMMSShh format. This is only required when passing time format information.

WW-EDITED-DATE

A 50 character string defining the format of the date editing required. This format is very flexible. See the remarks for the possible values together with some examples.

Output parameters

WW-EDITED-DATE

A 50 character alphanumeric field containing the edited date.

Remarks

This function is designed to allow a date to be edited in a very flexible way.

The following table shows the values that can be passed to WW-EDITED-DATE - these can be strung together as required.

Format code | Notes | Example
D | zero suppressed day of month with st, nd, rd or th | 1st or 2nd or 3rd or 4th
d | zero suppressed day of month | 1 or 30
dd | 2 digit day of month | 01 or 30
ddd | 3 character day of week | Mon or Tue
dddd | Full day of week description | Monday or Tuesday
M | zero suppressed month number | 1 or 12
MM | 2 digit month number | 01 or 12
MMM | 3 character month description | Jan or Feb
MMMM | Full month description | January or February
y | 1 digit year (rarely used) | 1
yy | 2 digit year | 99 or 02
yyy | 3 digit year (rarely used) | 999 or 002
yyyy | 4 digit year | 1999 or 2002
Strings |  |
/ | editing character remains as '/' | /
- | editing character remains as '-' | -
{space} | spaces remain as passed |
'text' | text in quotes are passed unchanged | 'Today is'
Time |  |
H | zero suppress 24 hour | 1 or 23
HH | 2 digit 24 hour | 01 or 23
h | zero suppress 12 hour format | 1 or 12
hh | 2 digit 12 hour format | 01 or 12
m | zero suppressed minute | 1 or 59
mm | 2 digit minute | 01 or 59
s | zero suppressed second | 1 or 59
ss | 2 digit second | 01 or 59
t | single character AM/PM indicator | A or P
tt | 2 character AM/PM indicator | AM or PM

Note that there is a Short date, Long date and Report date that can be edited using the function EDIT-REPORT-DATE.

Some examples of using this function assuming the date 20050428 is passed.

Date format | Edited date
dd MMMM yyyy | 28 April 2005
MM/dd/yyyy | 04/28/2005
MM/dd/yyyy HH:mm | 04/28/2005 22:50
'Today is' dddd MMMM d yyyy | Today is Thursday April 28 2005

Sample code

MOVE 20050428 TO DATE-CCYYMMDD.

MOVE "dd MMMM yyyy" TO WW-EDITED-DATE.

PERFORM EDIT-FORMATTED-DATE.

MOVE WW-EDITED-DATE TO SHOW-EDITED-DATE.

Requirements

Version: Included in Encore 5.1 issue 005 and later

Copybooks: standard

See also

EDIT-REPORT-DATE


EDIT-NO-LEADING-SPACES

The EDIT-NO-LEADING-SPACES function is used to format a numeric value without leading spaces depending on the number of decimals. It can be useful when stringing together text with numbers.

Input parameters

NUM-VAL

A 12.6 signed value containing the number to be edited.

NUM-DEC

The number of decimals to be applied. Must be 0-6.

Output parameters

NUMB-R

The value edited without leading spaces to the appropriate number of decimals. Trailing sign.

Remarks

This function is used to edit a numeric field returning a string without leading spaces.

For example moving in the value '000000000123.000000' to NUM-VAL for zero decimals will return '123'.

Note that there are functions called 'EDIT-NO-LEADING-SPACES-0' for zero decimal editing, 'EDIT-NO-LEADING-SPACES-1' for 1 decimal editing etc. up to 'EDIT-NO-LEADING-SPACES-6'. This saves having to move a value to NUM-DEC before performing the routine. See the second example below.

Sample code

MOVE 000123 TO NUM-VAL.

MOVE 2 TO NUM-DEC.

PERFORM EDIT-NO-LEADING-SPACES.

MOVE NUMB-R TO STRING-WITHOUT-LEADING-SPACES. *> Returns '123.00'

* Use of routine to edit to zero decimals

MOVE 123 TO NUM-VAL.

PERFORM EDIT-NO-LEADING-SPACES-0.

MOVE NUMB-R TO STRING-WITHOUT-LEADING-SPACES. *> Returns '123'

Requirements

Version: Included in SYSPRO 6.0 issue 008 and later

Copybooks: standard

See also

EDIT-QUANTITY


EDIT-QUANTITY

The EDIT-QUANTITY function is used to format a numeric quantity depending on the number of decimals. It is often used by Report and Query programs.

Input parameters

QTY-TO-EDIT

A 7.3 signed value containing the quantity to be edited.

EDIT-DECIMALS

The number of decimals to be applied. Must be 0-6.

Output parameters

EDITED-QTY

The quantity edited to the appropriate number of decimals. Trailing sign.

Remarks

This function is used by programs where a quantity is to be displayed or printed to an appropriate number of decimals.

Note that if you are showing a quantity in a listview you should use EDIT-QUANTITY-LIST.

Sample code

MOVE INVWHS-NHD TO QTY-TO-EDIT.

MOVE INVMST-DEC TO EDIT-DECIMALS.

PERFORM EDIT-QUANTITY.

MOVE EDITED-QTY TO D-EDITED-QUANTITY.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

EDIT-QUANTITY-LIST, EDIT-NO-LEADING-SPACES


EDIT-QUANTITY-LIST

The EDIT-QUANTITY-LIST function is used to format a numeric quantity depending on the number of decimals. The edited value has a leading sign for use in listviews.

Input parameters

QTY-TO-EDIT

A 7.3 signed value containing the quantity to be edited.

EDIT-DECIMALS

The number of decimals to be applied. Must be 0-6.

Output parameters

EDITED-QTY

The quantity edited to the appropriate number of decimals. Leading sign.

Remarks

This function is used by programs where a quantity is to be shown in a listview column. If signed a leading minus sign is included.

Note that if you are printing or showing a quantity in a Query use EDIT-QUANTITY.

Note that from SYSPRO 6.0 issue 009 there is a company option that configures how this function works. It is used to either edit the quantity to the exact number of decimals passed (the new option) or to always edit the quantity to three decimals (the default).

Sample code

MOVE INVWHS-NHD TO QTY-TO-EDIT.

MOVE INVMST-DEC TO EDIT-DECIMALS.

PERFORM EDIT-QUANTITY-LIST.

MOVE EDITED-QTY TO D-BRW-QTY-ON-HAND.

Requirements

Version: Included in Encore 5.0 and later. New company option available from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

EDIT-QUANTITY


EDIT-REPORT-DATE

The EDIT-REPORT-DATE function is used to format the current company date (stored in the SYSPRO standard date format) to the report date format defined in the System setup program.

Input parameters

None

Output parameters

WW-EDITED-DATE

A 50 character alphanumeric field containing the edited date.

Remarks

This routine formats the current company date into the Report date format. This makes use of the EDIT-DATE-TO-USER-FORMAT routine passing the R parameter.

In addition the current operating system time is available for formatting.

Examples of the formatting capability is shown below. All these assume the date to be formatted is 28th April 2005 at 10:15 am

Date format | Edited date
dd MMMM yyyy | 28 April 2005
MM/dd/yyyy | 04/28/2005
MM/dd/yyyy HH:mm | 04/28/2005 22:50
dddd MMMM d yyyy hh:mm tt | Thursday April 28 2005 10:15 AM

Sample code

PERFORM EDIT-REPORT-DATE.

MOVE WW-EDITED-DATE TO EDITED-REPORT-DATE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

EDIT-DATE-TO-USER-FORMAT, EDIT-FORMATTED-DATE


ENCRYPT-PLAIN-TEXT

The ENCRYPT-PLAIN-TEXT function is designed to provide a simple, reversible, encryption algorithm for short strings.

A common use is to store passwords to third party systems where these passwords are required to be passed by your application.

See DECRYPT-CIPHER-TEXT to decode the stored string.

Input parameters

LINK-SEED-TEXT

This is a 50 character string that will be used to scramble your plain text. It is recommended you use a combination of uppercase letters, lowercase letters and digits.

LINK-PLAIN-TEXT

This is your string to be encrypted. You can pass up to 50 characters.

Output parameters

LINK-CIPHER-TEXT

This is the returned encrypted text. It is recommended that if you only passed, say 15 characters that you only store the first 15 characters of this text. You must store the value in LINK-CIPHER-SUM together with this LINK-CIPHER-TEXT to be able to unencrypt the text later.

LINK-CIPHER-SUM

This is a three digit checksum that must be stored together with LINK-CIPHER-TEXT.

Remarks

This function is designed to allow you to encrypt short strings (up to 50 characters) quickly and easy.

Note this routine is not unbreakable. It uses a simple proprietary routine to encode and decode the strings. It is mainly used to store fairly sensitive data in a format that is not easily viewable.

Typical usages include storing passwords or other sensitive information that must be passed by your application to another application. In this case it is advisable not to store the password in an unencrypted format on a data file where someone may easily see it.

The result of the encryption routine generates a string (cipher text) the same length as the initial text (plain text). In addition a three digit checksum is also returned. The cipher text and the check sum are required for a successful decode.

Use the DECRYPT-CIPHER-TEXT function to decode the stored string.

Sample code

* Encrypt a password for later use

ENCRYPT-PASS.

MOVE "AbSD2ZJq0W8hPf61" TO LINK-SEED-TEXT. *> Seed

MOVE D-ENTERED-PASSWORD TO LINK-PLAIN-TEXT.

PERFORM ENCRYPT-PLAIN-TEXT.

MOVE LINK-CIPHER-TEXT TO SAVED-ENCRYPTED-TEXT.

MOVE LINK-CIPHER-SUM TO SAVED-ENCRYPTED-CHECKSUM.

* Decrypt password from saved fields

DECRYPT-PASS.

MOVE "AbSD2ZJq0W8hPf61" TO LINK-SEED-TEXT. *> Seed

MOVE SAVED-ENCRYPTED-TEXT TO LINK-CIPHER-TEXT.

MOVE SAVED-ENCRYPTED-CHECKSUM TO LINK-CIPHER-SUM.

PERFORM DECRYPT-CIPHER-TEXT.

MOVE LINK-PLAIN-TEXT TO ORIGINAL-PASSWORD.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

DECRYPT-CIPHER-TEXT


EXECUTE-COMMAND-ON-CLIENT

The EXECUTE-COMMAND-ON-CLIENT function is used to call any operating system or third party executable.

In a Client/Server environment this will be issued on the Client PC. This will always be a Windows environment.

You can optionally pass an initial start-in directory. This will cause the system to change to this directory before the command is executed.

Input parameters

LINK-EXTRA-1

This is the operating system command to be executed on the client PC. It can contain command line parameters.

LINK-EXTRA-2

This is an optional directory that the system will change to before the command is executed.

Output parameters

none

Remarks

You must ensure that spacey file names are surrounded with quotes. See the QUOTE-VALID-FILE-NAME function.

In a client/server system the command is executed on the client PC.

In a mapped drive system the command is executed on the client PC.

Parameter expansion

The command passed in LINK-EXTRA-1 will have parameter expansion applied. This means that the following parameters will be expanded to their actual values at run-time.

  • %oper - operator code

  • %coid - company id

  • %group - operator primary group code

For example the following command line

MyApp.exe /operator=%oper /company=%coid /group=%group

could be expanded at run time to:

MyApp.exe /operator=ADMIN /company=1 /group=ADMIN

Sample code

* Issue a command on the Client PC

MOVE "COPY C:\TEMP\ABC.TXT C:\TEMP\DEF.TXT" TO LINK-EXTRA-1.

PERFORM EXECUTE-COMMAND-ON-CLIENT.

Requirements

Version: Included in Encore 5.0 and later. The parameter expansion is available from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

spacey file names, EXECUTE-COMMAND-ON-SERVER, QUOTE-VALID-FILE-NAME, S-OSCMD


EXECUTE-COMMAND-ON-SERVER

The EXECUTE-COMMAND-ON-SERVER function is used to call any operating system or third party executable.

In a Client/Server environment this will be issued on the Server. Note that this may be a Windows or Unix environment.

You can optionally pass an initial start-in directory when using a Windows Server. This will cause the system to change to this directory before the command is executed.

Input parameters

LINK-EXTRA-1

This is the operating system command to be executed on the server. It can contain command line parameters.

LINK-EXTRA-2

This is an optional directory that the system will change to before the command is executed. On Unix this must be blank.

Output parameters

none

Remarks

You must ensure that spacey file names are surrounded with quotes. See the QUOTE-VALID-FILE-NAME function.

In a client/server system the command is executed on the server.

In a mapped drive system the command is executed on the client PC.

Parameter expansion

The command passed in LINK-EXTRA-1 will have parameter expansion applied. This means that the following parameters will be expanded to their actual values at run-time.

  • %oper - operator code

  • %coid - company id

  • %group - operator primary group code

For example the following command line

MyApp.exe /operator=%oper /company=%coid /group=%group

could be expanded at run time to:

MyApp.exe /operator=ADMIN /company=1 /group=ADMIN

Sample code

* Issue a command on the Server PC

IF LINK-OS = "U"

MOVE "cp /tmp/abc.txt /tmp/def.txt" TO LINK-EXTRA-1

ELSE

MOVE "COPY C:\TEMP\ABC.TXT C:\TEMP\DEF.TXT" TO LINK-EXTRA-1.

PERFORM EXECUTE-COMMAND-ON-SERVER.

Requirements

Version: Included in Encore 5.0 and later. The parameter expansion is available from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

spacey file names, EXECUTE-COMMAND-ON-CLIENT, QUOTE-VALID-FILE-NAME, S-OSCMDS


EXPAND-LINK-EXTRA

The EXPAND-LINK-EXTRA function is used to expand parameters in the common field LINK-EXTRA.

Up to 9 parameters, together with their expanded values, are passed in LINK-EXPAND.

Input parameters

LINK-EXTRA

A string that can contain parameters to be expanded.

LINK-EXPX1

The number of parameters passed (1-9).

LINK-EXPAND-VAR(x)

Up to 9 parameters to be replaced by their corresponding values in LINK-EXPAND-VAL(x)

LINK-EXPAND-VAL(x)

Up to 9 parameter values to be placed into LINK-EXTRA.

Output parameters

LINK-EXTRA

The original string with any parameters expanded to their values.

Remarks

This function is used to generically search and replace parameters with a corresponding value.

For example

Suppose you have a command line that could contain the parameters %oper and %coid and these are to be replaced with the current operator code and company id respectively.

In this case the command to be parsed is passed in LINK-EXTRA and the parameters are placed in the LINK-EXPAND-VAR(x) and LINK-EXPAND-VAL(x) occurrences and the value 2 moved to LINK-EXPX1.

Note that you must initialize the field LINK-EXPAND before moving in the parameters and their values as this field redefines other fields.

After the PERFORM EXPAND-LINK-EXTRA function has completed any occurrences of %oper and %coid will be expanded to their values.

Notes about parameters and their values

The parameters can appear anywhere and any number of times in the input string.

Up to 9 parameters can be passed, remember to move the number of parameters to LINK-EXPX1.

The function works as follows:

The function starts at the first character position in the input string and compares this with the input parameter in LINK-EXPAND-VAR(1).

If a match is found then the parameter in the input string is replaced with the value in LINK-EXPAND-VAL(1) If this is spaces then the parameter in the input string is simply removed. The character position after the replacement value will be the next character position in the input string to be processed.

If no match is found with the first parameter then the second parameter will be verified, and so on until all the parameters defined in LINK-EXPX1 have been verified.

Once this process has completed for all the parameters then the next character position in the input string is processed, and so on until the end of the input string.

Sample code

*

** Example code to replace %oper with the current operator code

** and %coid with the current company id

MOVE "MyApp.EXE /operator=%oper /company=%coid" TO LINK-EXTRA.

*

INITIALIZE LINK-EXPAND.

MOVE 1 TO LINK-EXPX1.

MOVE "%oper" TO LINK-EXPAND-VAR(LINK-EXPX1).

MOVE OPERATOR-CODE TO LINK-EXPAND-VAL(LINK-EXPX1).

*

ADD 1 TO LINK-EXPX1.

MOVE "%coid" TO LINK-EXPAND-VAR(LINK-EXPX1).

MOVE COMPID TO LINK-EXPAND-VAL(LINK-EXPX1).

*

PERFORM EXPAND-LINK-EXTRA.

*

** Example output: MyApp.EXE /operator=ADMIN /company=1

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later

Copybooks: standard

See also

EXPAND-WW-FILE-NAME


EXPAND-WW-FILE-NAME

The EXPAND-WW-FILE-NAME function is used to expand a file name that can contain special parameters such as $d to represent a data directory. These parameterized file names are used in the standard SYSPRO data dictionary and the Report Writer data dictionary.

Input parameters

WW-FILE-NAME

A file name that can contain parameters as defined below:

$d | the default data directory for the current company
$w | the working directory
$s | the snapshot directory
$t | the temporary directory
$c | the current company id
$g | the shared General Ledger id
$i | the shared Inventory id
$e | the file extension for this operating system (e.g. '.DAT')

Output parameters

WW-FILE-NAME

The built file name with any parameters expanded to their current values.

Remarks

This function is used to expand a parameterized file name. Any character other that the parameters accepted remain unchanged.

Note that a generic parameter expansion function is available using EXPAND-LINK-EXTRA.

The topic Shared Inventory Files contains a table listing all modules (and files) that use the shared inventory id.

Sample code

MOVE "$d$cARSMST$e" TO WW-FILE-NAME.

PERFORM EXPAND-WW-FILE-NAME.

MOVE WW-FILE-NAME TO FULL-PATH-OF-ARSMST.

* In the above example the parameters could be:

* $d – C:\Syspro\Data\

* $c – A

* $e - .DAT (on Windows)

* result in WW-FILE-NAME is:

* C:\Syspro\Data\AARSMST.DAT

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

BUILD-FILE-NAME, EXPAND-LINK-EXTRA


FILTER-ACCESS

The FILTER-ACCESS function is used to verify whether the operator is allowed access to a specific type of code, field or activity.

The system administrator can define which warehouses, A/R and A/P branches, banks, activities, fields, salespersons and job classifications can be accessed by each operator - it is the programs' responsibility to check the access. If access is denied then this function will return a flag. It is recommended that you use the specific functions to verify access such as FILTER-ACCESS-WH and FILTER-ACCESS-FIELD rather than this function.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS functions.

Input parameters

WW-ACCESS-FIELD

The code to be tested.

Note that for access type 100 (customer access) the fields WW-ACCESS-CUS and WW-ACCESS-SLS should be used.

WW-ACCESS-NUM

The number of the field or activity to be tested

WW-ACCESS-TYPE

The access type:

1 – Warehouse

2 – A/R Branch

3 – A/P Branch

4 – Bank

5 – Activity

6 – Field

7 – Salesperson

8 - Job Classification

9 - CMS Account

10 - CMS Contact

100 - Customer (e.net only)

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses a warehouse, branch, bank, salesperson, job classification, account, contact or one of the protected activities or fields the program must verify whether access is allowed.

It is recommended to use the individual routines as follows:

FILTER-ACCESS-WH

FILTER-ACCESS-ARBR

FILTER-ACCESS-APBR

FILTER-ACCESS-BANK

FILTER-ACCESS-TT

FILTER-ACCESS-FIELD

FILTER-ACCESS-REP

FILTER-ACCESS-JOBCL

FILTER-ACCESS-CUS (e.net only)

FILTER-ACCESS-ACCOUNT

FILTER-ACCESS-ACCOUNT-MAINT

FILTER-ACCESS-CONTACT

FILTER-ACCESS-CONTACT-MAINT

If the access has been denied then a flag is returned. If you wish to display a message box then see VERIFY-ACCESS.

Sample code

MOVE 1 TO WW-ACCESS-TYPE. *> Warehouse

MOVE INVWHS-WH TO WW-ACCESS-FIELD.

PERFORM FILTER-ACCESS.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-WH, FILTER-ACCESS-ARBR, FILTER-ACCESS-APBR, FILTER-ACCESS-BANK, FILTER-ACCESS-TT, FILTER-ACCESS-FIELD, FILTER-ACCESS-REP, FILTER-ACCESS-JOBCL, FILTER-ACCESS-CUS, FILTER-ACCESS-ACCOUNT, FILTER-ACCESS-ACCOUNT-MAINT, FILTER-ACCESS-CONTACT, FILTER-ACCESS-CONTACT-MAINT


FILTER-ACCESS-ACCOUNT

The FILTER-ACCESS-ACCOUNT function is used to verify whether the operator is allowed access to a CMS Account. The Account uses the Salesperson, AR branch and Account type as a filter. The system administrator can define which account types can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-ACCOUNT function.

Input parameters

WW-ACCESS-FIELD

Must be cleared before the rest of the fields are populated.

WW-ACCESS-ACC-SLS

The Salesperson from the account (CRMACC-SLSP).

WW-ACCESS-ACC-BRN

The Branch from the account (CRMACC-BR).

WW-ACCESS-ACC-TYP

The Account type from the account (CRMACC-TYPE).

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses a Contact Management Account this routine should be used to verify whether the operator has access to the Account.

If the access has been denied then a flag is returned.

When developing a maintenance program you should use the FILTER-ACCESS-ACCOUNT-MAINT function as this ignores whether the administrator has selected the 'Filter reports and browses' option.

Sample code

*

** Check Account security filter

if operator-access-acc = "Y"

move spaces to ww-access-field

move crmacc-slsp to ww-access-acc-sls

move crmacc-br to ww-access-acc-brn

move crmacc-type to ww-access-acc-typ

perform filter-access-account

if ww-access-ok <> "Y"

go to ignore-this-account.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP2 and later

Copybooks: standard

See also

FILTER-ACCESS, FILTER-ACCESS-ACCOUNT-MAINT, VERIFY-ACCESS-ACCOUNT


FILTER-ACCESS-ACCOUNT-MAINT

The FILTER-ACCESS-ACCOUNT0MAINT function is used to verify whether the operator is allowed to maintain a CMS Account. The Account uses the Salesperson, AR branch and Account type as a filter. The system administrator can define which account types can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-ACCOUNT function.

If you are developing a report or browse then you should use the FILTER-ACCESS-ACCOUNT function.

Input parameters

WW-ACCESS-FIELD

Must be cleared before the rest of the fields are populated.

WW-ACCESS-ACC-SLS

The Salesperson from the account (CRMACC-SLSP).

WW-ACCESS-ACC-BRN

The Branch from the account (CRMACC-BR).

WW-ACCESS-ACC-TYP

The Account type from the account (CRMACC-TYPE).

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a maintenance program accesses a Contact Management Account this routine should be used to verify whether the operator has access to the Account.

If the access has been denied then a flag is returned.

Sample code

*

** Test for Account Security

MOVE SPACES TO WW-ACCESS-FIELD.

MOVE CRMACC-SLSP TO WW-ACCESS-ACC-SLS.

MOVE CRMACC-BR TO WW-ACCESS-ACC-BRN.

MOVE CRMACC-TYPE TO WW-ACCESS-ACC-TYP.

PERFORM FILTER-ACCESS-ACCOUNT-MAINT.

IF WW-ACCESS-OK <> "Y"

GO TO PREVIOUS-ACCOUNT-2.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP2 and later

Copybooks: standard

See also

FILTER-ACCESS, FILTER-ACCESS-ACCOUNT, VERIFY-ACCESS-ACCOUNT


FILTER-ACCESS-APBR

The FILTER-ACCESS-APBR function is used to verify whether the operator is allowed access to the passed AP branch code. The system administrator can define which branches can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-APBR function.

Input parameters

WW-ACCESS-FIELD

The AP branch to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses an AP branch code this routine should be used to determine whether the current operator or role has access to the branch.

If the access has been denied then a flag is returned.

Sample code

MOVE APSMST-ACL TO WW-ACCESS-FIELD.

PERFORM FILTER-ACCESS-APBR.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

FILTER-ACCESS, VERIFY-ACCESS-APBR


FILTER-ACCESS-ARBR

The FILTER-ACCESS-ARBR function is used to verify whether the operator is allowed access to the passed AR branch code. The system administrator can define which branches can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-ARBR function.

Input parameters

WW-ACCESS-FIELD

The AR branch to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses an AR branch code this routine should be used to determine whether the current operator or role has access to the branch.

If the access has been denied then a flag is returned.

Sample code

MOVE ARSMST-BR TO WW-ACCESS-FIELD.

PERFORM FILTER-ACCESS-ARBR.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

FILTER-ACCESS, VERIFY-ACCESS-ARBR


FILTER-ACCESS-BANK

The FILTER-ACCESS-BANK function is used to verify whether the operator is allowed access to the passed bank code. The system administrator can define which banks can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-BANK function.

Input parameters

WW-ACCESS-FIELD

The bank to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses a bank code this routine should be used to determine whether the current operator or role has access to the bank.

If the access has been denied then a flag is returned.

Sample code

MOVE ARSMST-VBK TO WW-ACCESS-FIELD.

PERFORM FILTER-ACCESS-BANK.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

FILTER-ACCESS, VERIFY-ACCESS-BANK


FILTER-ACCESS-CONTACT

The VERIFY-ACCESS-CONTACT function is used to verify whether the operator is allowed access to a CMS Contact. The Contact uses the Property, Class, Type, Category and Territory as a filter. The system administrator can define which Property, Class, Type, Category and Territories can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-CONTACT function.

Input parameters

WW-ACCESS-FIELD

Must be cleared before the rest of the fields are populated.

WW-ACCESS-CON-PRP

The Property from the contact (CRMCON-PROPERTY).

WW-ACCESS-CON-CLS

The Class from the contact (CRMCON-CLASS).

WW-ACCESS-CON-TYP

The Type from the contact (CRMCON-TYPE).

WW-ACCESS-CON-CAT

The Category from the contact (CRMCON-CAT).

WW-ACCESS-CON-TER

The Territory from the contact (CRMCON-TERRITORY).

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses a Contact Management Contact this routine should be used to verify whether the operator has access to the Contact.

If the access has been denied then a flag is returned.

Sample code

*

** Contact Security

if operator-access-con = "Y"

move spaces to ww-access-field

move crmcon-property to ww-access-con-prp

move crmcon-class to ww-access-con-cls

move crmcon-type to ww-access-con-typ

move crmcon-cat to ww-access-con-cat

move crmcon-territory to ww-access-con-ter

perform filter-access-contact

if ww-access-ok <> "Y"

go to ignore-this-contact.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP2 and later

Copybooks: standard

See also

FILTER-ACCESS, VERIFY-ACCESS-CONTACT


FILTER-ACCESS-CONTACT-MAINT

The VERIFY-ACCESS-CONTACT function is used to verify whether the operator is allowed to maintain a CMS Contact. The Contact uses the Property, Class, Type, Category and Territory as a filter. The system administrator can define which Property, Class, Type, Category and Territories can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-CONTACT function.

If you are developing a report or browse then you should use the FILTER-ACCESS-CONTACT function.

Input parameters

WW-ACCESS-FIELD

Must be cleared before the rest of the fields are populated.

WW-ACCESS-CON-PRP

The Property from the contact (CRMCON-PROPERTY).

WW-ACCESS-CON-CLS

The Class from the contact (CRMCON-CLASS).

WW-ACCESS-CON-TYP

The Type from the contact (CRMCON-TYPE).

WW-ACCESS-CON-CAT

The Category from the contact (CRMCON-CAT).

WW-ACCESS-CON-TER

The Territory from the contact (CRMCON-TERRITORY).

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a maintenance program accesses a Contact Management Contact this routine should be used to verify whether the operator has access to the Contact.

If the access has been denied then a flag is returned.

Sample code

*

** Test for Contact Security

MOVE SPACES TO WW-ACCESS-FIELD.

MOVE CRMCON-PROPERTY TO WW-ACCESS-CON-PRP.

MOVE CRMCON-CLASS TO WW-ACCESS-CON-CLS.

MOVE CRMCON-TYPE TO WW-ACCESS-CON-TYP.

MOVE CRMCON-CAT TO WW-ACCESS-CON-CAT.

MOVE CRMCON-TERRITORY TO WW-ACCESS-CON-TER.

PERFORM FILTER-ACCESS-CONTACT-MAINT.

IF WW-ACCESS-OK <> "Y"

GO TO PREVIOUS-CONTACT-2.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP2 and later

Copybooks: standard

See also

FILTER-ACCESS, FILTER-ACCESS-CONTACT, VERIFY-ACCESS-CONTACT


FILTER-ACCESS-CUS

Note this security function is for e.net solutions business objects only and should not be used by SYSPRO programs.

The FILTER-ACCESS-CUS function is used to verify whether the operator is allowed access to the passed Customer code. The system administrator can define which Customers can be accessed by each operator - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

Input parameters

WW-ACCESS-CUS

The Customer to be tested.

WW-ACCESS-SLS

The salesperson that the customer belongs to.

Note that this field must be passed as the administrator can define that any customers belonging to a salesperson can be allowed.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever an e.net business object accesses a customer this routine should be used to determine whether the current operator code has access to the customer.

Note that the salesperson must be passed for this function to work successfully..

If the access has been denied then a flag is returned.

Sample code

MOVE ARSMST-CUS TO WW-ACCESS-CUS.

MOVE ARSMST-SLSP TO WW-ACCESS-SLS.

PERFORM FILTER-ACCESS-CUS.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in SYSPRO 6.0 Issue 006 and later

Copybooks: standard

See also

FILTER-ACCESS


FILTER-ACCESS-FIELD

The FILTER-ACCESS-FIELD function is used to verify whether the operator is allowed access to a specific field. The system administrator can define which fields can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-FIELD function.

Input parameters

WW-ACCESS-NUM

The field to be tested. See IMPSEC.IMP for a list of activities.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses one of the listed fields in the operator or role maintenance program this routine should be used to determine whether the current operator or role has access to the field.

If the access has been denied then a flag is returned.

Sample code

MOVE 1 TO WW-ACCESS-NUM. *> A/R credit limit

PERFORM FILTER-ACCESS-FIELD.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

IMPSEC.IMP, FILTER-ACCESS, VERIFY-ACCESS-FIELD


FILTER-ACCESS-JOBCL

The FILTER-ACCESS-JOBCL function is used to verify whether the operator is allowed access to the passed job classification. The system administrator can define which job classifications can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-JOBCL function.

Input parameters

WW-ACCESS-FIELD

The job classification to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses a job this routine should be used to determine whether the current operator or role has access to the job classification.

If the access has been denied then a flag is returned.

Sample code

MOVE WIPMST-CLS TO WW-ACCESS-FIELD.

PERFORM FILTER-ACCESS-JOBCL.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.1 issue 004 and later

Copybooks: standard

See also

FILTER-ACCESS, VERIFY-ACCESS-JOBCL


FILTER-ACCESS-REP

The FILTER-ACCESS-REP function is used to verify whether the operator is allowed access to a specific salesperson code. The system administrator can define which salespersons can be accessed by each operator - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-REP function.

Input parameters

WW-ACCESS-FIELD

The salesperson to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses a salesperson this routine should be used to determine whether the current operator code has access to the salesperson.

If the access has been denied then a flag is returned.

Sample code

MOVE ARSMST-SLSP TO WW-ACCESS-FIELD.

PERFORM FILTER-ACCESS-REP.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

FILTER-ACCESS, VERIFY-ACCESS-REP


FILTER-ACCESS-TT

The FILTER-ACCESS-TT function is used to verify whether the operator is allowed access to an activity. The system administrator can define which activities can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-TT function.

Input parameters

WW-ACCESS-NUM

The activity to be tested. See IMPSEC.IMP for a list of activities.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses one of the listed activities in the operator or role maintenance program this routine should be used to determine whether the current operator or role has access to the activity.

If the access has been denied then a flag is returned.

Sample code

MOVE 1 TO WW-ACCESS-NUM. *> Stock receipts

PERFORM FILTER-ACCESS-TT.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

IMPSEC.IMP, FILTER-ACCESS, VERIFY-ACCESS-TT


FILTER-ACCESS-WH

The FILTER-ACCESS-WH function is used to verify whether the operator is allowed access to the passed warehouse code. The system administrator can define which warehouses can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will return a flag.

If you wish your program to display an error message indicating that access is denied then consider the equivalent VERIFY-ACCESS-WH function.

Input parameters

WW-ACCESS-FIELD

The warehouse to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

Remarks

Whenever a program accesses a warehouse code this routine should be used to determine whether the current operator or role has access to the warehouse.

If the access has been denied then a flag is returned.

Sample code

MOVE INVWHS-WH TO WW-ACCESS-FIELD.

PERFORM FILTER-ACCESS-WH.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

FILTER-ACCESS, VERIFY-ACCESS-WH


FMT-POST

The FMT-POST function is used to edit a United States Zip Code into a 5-4 format. This takes a 9 character code and edits it to 5-4.

Input parameters

PST-CDE

A 9 character postal/zip code.

Output parameters

PST-CDE

A 10 character edited zip code.

Remarks

This function uses the Company setup option to edit postal/zip codes as 5-4. Simply pass it a 9 character postal/zip code and it returns a 10 character edited value to be displayed or printed.

Sample code

MOVE ARSMST-ADD6 TO PST-CDE.

PERFORM FMT-PST.

MOVE PST-CDE TO EDITED-POSTAL-ZIP-CODE-10.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also


GENERATE-GUID

The GENERATE-GUID function is used to generate a GUID (Globally Unique ID) for use with the Contact Managements system. It returns the GUID in both 16 byte and 38 byte formats.

Input parameters

none

Output parameters

WW-GUID16

GUID in a 16 byte format.

WW-GUID38

GUID in a 38 byte format.

Remarks

This function is to be used to generate a GUID for use with the Contact Management System. The returned GUID should be used as a ContactId in the Contact Master File (CRMCON / CrmContact).

See the article Using GUIDs for more information.

Contact Management and use of a ContactId

There is a new Contact Management System (CMS) included in Issue 010 SP1. This is developed using many of the new controls, however it is still a traditional SYSPRO application and therefore works in a client/server environment and with ISAM or SQL data storage.

One of the techniques used for the first time in CMS is that the key to the Contact master table (CRMCON / CrmContact) is a GUID.

A GUID is a Globally Unique ID. This is a 128 bit (16 character) field that is guaranteed to be unique.

Within your Net Express programs this is stored and used as a X(16) field. Also in a record layout it is stored as X(16). However in the data dictionary it is defined as a 'uniqueidentifier' column (the field is defined as Alphanumeric but also the field DDSFLD-GUID is a 'G').

In addition in a SQL Server environment the ContactId has a data type of 'uniqueidentifier'.

The data dictionary has been enhanced to cater for GUIDs and a few of the utility programs have also been changed.

It is highly recommended that a GUID is never displayed or printed as it's a meaningless string to an operator. However some programs, such as generic utilities, may need to view the contents of a column. To assist with this there are two new functions for converting a 16 character GUID to an industry standard 38 character format. They are:

CONVERT-GUID16-TO-GUID38

CONVERT-GUID38-TO-GUID16

In addition if your program reads data generically and wants to show the key it is recommended that when passed a ContactId you show the Contact name (rather than a GUID in any format). This function (CMS-READ-CONTACT-NAME-FRM-GUID) is to be used for this purpose.

The reverse is also available allowing you to read the Contact Id passing a Contact name. The function is called CMS-READ-CONTACT-GUID-FRM-NAME. Note that if there are multiple Contacts with the same name then only one Contact Id will be returned.

Generic functions

The generic functions to such as Notepad, Multimedia and Custom Forms must not use a GUID as the generic key - in this case the GUID38 format is used.

Warning about using GUID16 data

It's important to realize that a GUID can contain virtually any Binary value and care must be taken when storing this information (for example in a text file) or passing information between systems.

For example if you wish to store a GUID, such as a ContactId, in a listview column you must use the GUID38 format to avoid spurious problems populating or using the Listview.

Sample code

* Generate a new GUID

PERFORM GENERATE=GUID.

MOVE WW-GUID16 TO GUID16-FORMAT-FIELD.

MOVE WW-GUID38 TO GUID38-FORMAT-FIELD.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP1 port 15 and later.

Copybooks: standard

See also

Data Dictionary Conventions, Using GUIDs, CMS-READ-CONTACT-GUID-FRM-NAME, CONVERT-GUID16-TO-GUID38, CONVERT-GUID38-TO-GUID16.


GENERATE-VALID-FILE-NAME

The GENERATE-VALID-FILE-NAME function is used to ensure that an arbitrary input string contains only the letters A-Z, a-z and 0-9. This is useful to accept a field (such as an operator code) and generate a string that can be used as part of a file name without the possibility of accidentally including characters that are invalid in a file name.

Input parameters

WW-FILE-NAME

The input string to be used as a file name

Output parameters

WW-FILE-NAME

A string that only contains letters and numbers and no embedded spaces.

Remarks

In several cases you may wish to generate a file name (or temporary file name) that contains a key field as part of the file name.

During the development process your code may work, however in a real-world environment, the key field may inadvertently contain characters that are invalid in a file name.

For example you may wish to create a file named settings\ADMIN_To_Do_List.TXT where 'ADMIN' is the operator code.

However if the operator code was "FRED:1' then this will fail as a colon (':') is not a valid character when included in a file name.

Similarly if the operator code was 'SUE J' then the space in the operator code could cause your code to fail unless you used the QUOTE-VALID-FILE-NAME function.

The GENERATE-VALID-FILE-NAME function takes any string as an input - the output contains only the original string where there are the characters A-Z, a-z and 0-9. Any embedded spaces will also be removed.

In the above examples 'FRED:1' becomes 'FRED1' and 'SUE J' becomes 'SUEJ'.

Sample code

* generate settings\{oper}_To_Do_List.TXT

MOVE OPERATOR-CODE TO WW-FILE-NAME.

PERFORM GENERATE-VALID-FILE-NAME.

MOVE SPACES TO TO-DO-FILE-NAME.

STRING

"settings" DELIMITED BY SIZE

LINK-OS-SLASH DELIMITED BY SIZE

WW-FILE-NAME DELIMITED BY " "

"_To_Do_List_.TXT" DELIMITED BY SIZE

Requirements

Version: Included in SYSPRO 6.1 and later

Copybooks: Standard

See also

spacey file name, QUOTE-VALID-FILE-NAME


GET-AP-PAY-LOCK

The GET-AP-PAY-LOCK function is used to acquire a lock to process the A/P Payment Release file.

It is important to acquire a lock for a supplier before processing the A/P Payment Release information for the supplier. There is also a CLEAR-AP-PAY-LOCK and a DELETE-AP-PAY-LOCK-FILE function.

Input parameters

LINK-EXTRA

You must pass the supplier code to be locked to this field

Output parameters

LINK-EXTRA

A return status indicating whether the lock was acquired successfully.

Spaces – Lock acquired ok

Remarks

If you require to process A/P Payments Releases for a supplier then you must use this function to acquire a lock to ensure that another operator is not processing the payments for the same supplier.

You must pass the supplier code in LINK-EXTRA before using this function.

When you have finished with the supplier then you should use the CLEAR-AP-PAY-LOCK function to remove the lock for the supplier.

Note that if there is a system crash after the lock has been acquired then the function DELETE-AP-PAY-LOCK-FILE should be used to physically delete the lock file and clear any locks. This is performed by the A/P Balance function.

Sample code

* About to process A/P Payment Release for supplier

MOVE APSMST-SUP TO LINK-EXTRA. *> Move in supplier code

PERFORM GET-AP-PAY-LOCK.

IF LINK-EXTRA = SPACES

PERFORM PROCESS-PAYMENTS-FOR-SUPPLIER

MOVE D-SUPPLIER TO LINK-EXTRA

PERFORM CLEAR-AP-PAY-LOCK

ELSE

MOVE SPACES TO LINK-EXTRA

PERFORM UNABLE-TO-ACQUIRE-LOCK.

Requirements

Version: Included in Encore 5.1 issue 004 and later.

Copybooks: standard

See also

CLEAR-AP-PAY-LOCK, DELETE-AP-PAY-LOCK-FILE


GET-CLIENT-IMPACT-INI

The GET-CLIENT-IMPACT-INI function is used to determine the full path name to the IMPACT.INI file on the Client PC in a Client/Server system.

Input parameters

none

Output parameters

WW-FILE-NAME

The full path name of the Client IMPACT.INI is returned.

Remarks

This function is only to be used on a Client/Server system.

Sample code

* Retrieve the name of the Client IMPACT.INI

PERFORM GET-CLIENT-IMPACT-INI.

MOVE WW-FILE-NAME TO CLIENT-IMPACT-INI.

Requirements

Version: Included in SYSPRO 6.0 issue 007 and later. This function requires the Client program (IMPCSC.EXE) version 6.0.008 or later.

Copybooks: standard

See also

spacey file names, GET-DIRECTORY-ON-SERVER, SET-DIRECTORY-ON-SERVER, SET-DIRECTORY-ON-CLIENT, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSGETD


GET-COMPANY-LIST-ALL

The GET-COMPANY-LIST-ALL function is used to retrieve a list of all companies on your SYSPRO system. The list is returned as a space delimited string.

Input parameters

none

Output parameters

LINK-EXTRA

Space delimited list of company id's

Remarks

This function returns a list of company id's as a space delimited string. It will always include your current company id in the returned string.

In SYSPRO 6.1 and prior versions the company id is a single character in the range (0-9, A-Z).

For example the output could contain '02ABCZ'.

Note that from SYSPRO 7.0 it is our intention to increase the length of the company id field and therefore you should consider using the GET-COMPANY-LIST-ALL-COMMA function which returns the list of company id's as a comma separated list.

Also it's worth considering the e.net business object COMQCO that can be used to retrieve a list of companies. It not only returns the company id for each company but also the company name, database access type and various other parameters.

Sample code

PERFORM GET-COMPANY-LIST-ALL.

MOVE LINK-EXTRA TO COMPANY-LIST. *> e.g. '02ABCZ'

Requirements

Version: Included in SYSPRO 6.1 and later

Copybooks: standard

See also

GET-COMPANY-LIST-ALL-COMMA, GET-COMPANY-LIST-INV, GET-COMPANY-LIST-INV-COMMA


GET-COMPANY-LIST-ALL-COMMA

The GET-COMPANY-LIST-ALL-COMMA function is used to retrieve a list of all companies on your SYSPRO system. The list is returned as a comma separated space delimited string.

Input parameters

none

Output parameters

LINK-EXTRA

Comma separated space delimited list of company id's

Remarks

This function returns a list of company id's as a comma separated space delimited string. It will always include your current company id in the returned string.

In SYSPRO 6.1 and prior versions the company id is a single character in the range (0-9, A-Z).

For example the output could contain '0,2,A,B,C,Z'.

Note that from SYSPRO 7.0 it is our intention to increase the length of the company id field and therefore you should consider allowing for more than a single character as the company id.

Also it's worth considering the e.net business object COMQCO that can be used to retrieve a list of companies. It not only returns the company id for each company but also the company name, database access type and various other parameters.

Sample code

PERFORM GET-COMPANY-LIST-ALL-COMMA.

MOVE LINK-EXTRA TO COMPANY-LIST. *> e.g. '0,2,A,B,C,Z'

Requirements

Version: Included in SYSPRO 6.1 and later

Copybooks: standard

See also

GET-COMPANY-LIST-ALL, GET-COMPANY-LIST-INV, GET-COMPANY-LIST-INV-COMMA


GET-COMPANY-LIST-INV

The GET-COMPANY-LIST-INV function is used to retrieve a list of all companies on your SYSPRO system that share the same shared inventory id as the current company. The list is returned as a space delimited string.

Input parameters

none

Output parameters

LINK-EXTRA

Space delimited list of company id's

Remarks

This function returns a list of company id's that have the same shared inventory id as your current company. It will always include your current company id in the returned string.

In SYSPRO 6.1 and prior versions the company id is a single character in the range (0-9, A-Z).

For example the output could contain '02ABCZ'.

Note that from SYSPRO 7.0 it is our intention to increase the length of the company id field and therefore you should consider using the GET-COMPANY-LIST-INV-COMMA function which returns the list of company id's as a comma separated list.

Sample code

PERFORM GET-COMPANY-LIST-INV.

MOVE LINK-EXTRA TO COMPANY-LIST. *> e.g. '02ABCZ'

Requirements

Version: Included in SYSPRO 6.1 and later

Copybooks: standard

See also

GET-COMPANY-LIST-ALL, GET-COMPANY-LIST-ALL-COMMA, GET-COMPANY-LIST-INV-COMMA


GET-COMPANY-LIST-INV-COMMA

The GET-COMPANY-LIST-INV-COMMA function is used to retrieve a list of all companies on your SYSPRO system that share the same shared inventory id as the current company. The list is returned as a comma separated space delimited string.

Input parameters

none

Output parameters

LINK-EXTRA

Comma separated space delimited list of company id's

Remarks

This function returns a list of company id's that have the same shared inventory id as your current company. It will always include your current company id in the returned string.

In SYSPRO 6.1 and prior versions the company id is a single character in the range (0-9, A-Z).

For example the output could contain '0,2,A,B,C,Z'.

Note that from SYSPRO 7.0 it is our intention to increase the length of the company id field and therefore you should consider allowing for more than a single character as the company id.

Sample code

PERFORM GET-COMPANY-LIST-INV-COMMA.

MOVE LINK-EXTRA TO COMPANY-LIST. *> e.g. '0,2,A,B,C,Z'

Requirements

Version: Included in SYSPRO 6.1 and later

Copybooks: standard

See also

GET-COMPANY-LIST-ALL, GET-COMPANY-LIST-ALL-COMMA, GET-COMPANY-LIST-INV


GET-COMPUTER-DATE-TIME

The GET-COMPUTER-DATE-TIME function is used to retrieve and format the current computer date and time. In a client/server environment this is the operating system date and time of the server system.

Input parameters

none

Output parameters

COMPUTER-DATE

The current date in YYMMDD format

COMPUTER-CCYYMMDD

The current date in CCYYMMDD format

COMPUTER-TIME

The current time in HHMMSShh format. Where hh is a decimal 1/100th second

Remarks

This function is useful when storing, displaying or printing the current system date and/or time.

It is commonly used when starting a report to show the current time.

Sample code

PERFORM GET-COMPUTER-DATE-TIME.

MOVE COMPUTER-CCYYMMDD TO D-CURRENT-DATE.

MOVE COMPUTER-TIME TO D-CURRENT-TIME.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

PRINT-OPEN


GET-DATABASE-NAME

The GET-DATABASE-NAME function is used to lookup the name of the database for a specific company id.

When SYSPRO is running on SQL Server it stores the vast majority of the data in a single database per company. This function allows a program to determine the database name used for a specific company.

Input parameters

WW-COMPID

This is the company id that you require.

Output parameters

WW-FILE-NAME

This is the name of the database where the majority of company tables are stored.

If this field is blank then either the company does not exist or else it is a C-ISAM company.

Remarks

This function can be used by utility programs to access multiple companies data. You can access a table for any company using a fully qualified name – assuming you have the appropriate permission.

For example suppose you have two companies as follows:

Company A uses database SalesDatabase

Company B uses database WorkshopDatabase

If you are currently logged into company A then you can use the GET-DATABASE-NAME function for company B and build a table name for the A/R Master table as follows:

MOVE "B" TO WW-COMPID.

PERFORM GET-DATABASE-NAME.

MOVE SPACES TO FULL-TABLE-NAME.

STRING WW-FILE-NAME DELIMITED BY " "

".." DELIMITED BY SIZE

"ArCustomer" DELIMITED BY SIZE

INTO FULL-TABLE-NAME.

The field FULL-TABLE-NAME will contain WorkshopDatabase..ArCustomer

Sample code

MOVE "B" TO WW-COMPID.

PERFORM GET-DATABASE-NAME.

MOVE SPACES TO FULL-TABLE-NAME.

STRING WW-FILE-NAME DELIMITED BY " "

".." DELIMITED BY SIZE

"ArCustomer" DELIMITED BY SIZE

INTO FULL-TABLE-NAME.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

BUILD-FILE-NAME


GET-DIRECTORY-ON-CLIENT

The GET-DIRECTORY-ON-CLIENT function is used to determine the current directory on the client PC.

In a Client/Server environment this will be issued on the Client PC. This will always be a Windows environment.

Input parameters

none

Output parameters

LINK-EXTRA-1

The current directory is returned in this field. It will be quoted if spacey.

Remarks

If the current directory is spacey then it will be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

In a client/server system the command is executed on the client PC.

In a mapped drive system the command is executed on the client PC.

Sample code

* Retrieve the current directory

PERFORM GET-DIRECTORY-ON-CLIENT.

MOVE LINK-EXTRA-1 TO D-CURRENT-DIRECTORY.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file names, GET-DIRECTORY-ON-SERVER, SET-DIRECTORY-ON-SERVER, SET-DIRECTORY-ON-CLIENT, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSGETD


GET-DIRECTORY-ON-SERVER

The GET-DIRECTORY-ON-SERVER function is used to determine the current directory on the server.

In a Client/Server environment this will be issued on the Server. This may be a Windows or Unix system.

Input parameters

none

Output parameters

LINK-EXTRA-1

The current directory is returned in this field. It will be quoted if spacey.

Remarks

If the current directory is spacey then it will be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

In a client/server system the command is executed on the server.

In a mapped drive system the command is executed on the client PC.

Sample code

* Retrieve the current directory

PERFORM GET-DIRECTORY-ON-SERVER.

MOVE LINK-EXTRA-1 TO D-CURRENT-DIRECTORY.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file names, GET-DIRECTORY-ON-CLIENT, SET-DIRECTORY-ON-CLIENT, SET-DIRECTORY-ON-SERVER, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSGETDS


GET-ENVIRONMENT-STRING

The GET-ENVIRONMENT-STRING function is used to retrieve a 50 character string containing a description of the current SYSPRO environment. It is used by the Login and About dialog boxes.

Input parameters

none

Output parameters

WW-LINK-1

A 50 character environment string.

Remarks

This function uses the system configuration to return a 50 character string.

(previously this used to return whether the system was 16 or 32 bit but now only returns information about client/server environments).

It is not recommended to use this function as it is subject to change - it is designed to be used internally at Syspro.

Sample code

PERFORM GET-ENVIRONMENT-STRING.

MOVE SPACES TO D-DIALOG-BOX-HEADING.

STRING

"SYSPRO 6.0 " DELIMITED BY SIZE

WW-LINK-1 DELIMITED BY " "

INTO D-DIALOG-BOX-HEADING.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard


GET-GL-ENT-LOCK-EXCLUSIVE

The GET-GL-ENT-LOCK-EXCLUSIVE function is used to acquire a lock to process the G/L entries file.

It is important to acquire a lock before adding or posting to a G/L Entries file. There is also a GET-GL-ENT-LOCK-SHARED and a CLEAR-GL-ENT-LOCK function.

Input parameters

LINK-EXTRA-2

If you wish to acquire a lock on a company other than the current company then move in the company id to this field.

Output parameters

LINK-EXTRA

A return status indicating whether the lock was acquired successfully.

Spaces – Lock acquired ok

Remarks

If you require to add new entries to the G/L Entries file the you should acquire a lock using this function.

Remember to clear the lock afterwards using CLEAR-GL-ENT-LOCK.

Sample code

* Update G/L Entries

PERFORM GET-GL-ENT-LOCK-EXCLUSIVE.

IF LINK-EXTRA = SPACES

PERFORM UPDATE-GL-ENTRIES

ELSE

PERFORM UNABLE-TO-ACQUIRE-LOCK.

PERFORM CLEAR-GL-ENT-LOCK.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

GET-GL-ENT-LOCK-SHARED, CLEAR-GL-ENT-LOCK


GET-GL-ENT-LOCK-SHARED

The GET-GL-ENT-LOCK-SHARED function is used to acquire a lock to process the G/L entries file.

It is important to acquire a lock before adding or posting to a G/L Entries file. There is also a GET-GL-ENT-LOCK-EXCLUSIVE and a CLEAR-GL-ENT-LOCK function.

Input parameters

LINK-EXTRA-2

If you wish to acquire a lock on a company other than the current company then move in the company id to this field.

Output parameters

LINK-EXTRA

A return status indicating whether the lock was acquired successfully.

Spaces – Lock acquired ok

Remarks

If you require to add new entries to the G/L Entries file the you should acquire a lock using this function.

Remember to clear the lock afterwards using CLEAR-GL-ENT-LOCK.

Sample code

* Update G/L Entries

PERFORM GET-GL-ENT-LOCK-SHARED.

IF LINK-EXTRA = SPACES

PERFORM READ-GL-ENTRIES

ELSE

PERFORM UNABLE-TO-ACQUIRE-LOCK.

PERFORM CLEAR-GL-ENT-LOCK.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

GET-GL-ENT-LOCK-EXCLUSIVE, CLEAR-GL-ENT-LOCK


GET-GROUPS-FOR-OPERATOR

The GET-GROUPS-FOR-OPERATOR function is used to retrieve a list of all groups - primary and sub-groups - to which the current operator belongs.

Input parameters

none

Output parameters

WW-GROUP-CODE(x)

A table containing the list of primary and sub-groups.

The first occurrence is always the primary group.

Remarks

This function is used to retrieve the primary group and any sub-groups to which the current operator belongs.

The returned field WW-GROUP-TABLE contains the elements WW-GROUP-CODE(x) where x is between 1 and 160.

A blank group code is the end of the list (unless the full 160 groups are used).

You can use the function CHECK-IF-OPER-BELONGS-TO-GROUP to verify whether an operator belongs to a group.

Sample code

* Get list of groups for current operator

PERFORM GET-GROUPS-FOR-OPERATOR.

MOVE WW-GROUP-CODE(1) TO SAVE-PRIMARY-GROUPS.

MOVE WW-GROUP-CODE(2) TO SUB-GROUP-1.

MOVE WW-GROUP-CODE(3) TO SUB-GROUP-2.

Requirements

Version: Included in SYSPRO 6.0 Issue 008 and later.

Copybooks: standard

See also

CHECK-IF-OPER-BELONGS-TO-GROUP


GET-PASSWORD-INFO

The GET-PASSWORD-INFO function is used to find out whether there is already a password defined. This can then be used by your application to ask a password.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being tested.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

LINK-PASS-KEY

This is the key of the item being protected.

For example when setting the operator password this will be the operator code.

If you wish to set a password that is function based – for example a credit note – then you could use the phrase 'credit note' as the key. This will form part of the encryption key so a longer phrase is better than a short one.

Output parameters

LINK-PASS-OK

This flag indicates whether there is a password against the key.

Y – Yes

N – No password defined

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The GET-PASSWORD-INFO function allows your application to determine whether a password exists for the type and key.

Sample code

* Check if password to change a S/Order line price exists

MOVE SPACES TO LINK-PASS.

MOVE "-SOR03" TO LINK-PASS-TYP. *> See IMPPSS.IMP for codes

PERFORM GET-PASSWORD-INFO.

IF LINK-PASS-OK = "Y"

MOVE SPACES TO LINK-PASS

GO TO CREDIT-NOTE-IS-PROTECTED

ELSE

MOVE SPACES TO LINK-PASS

GO TO NO-PASSWORD.

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-OLD, SET-PASSWORD-NO-ASK, ADD-PASSWORD-CTL, DEL-PASSWORD


GET-PRINT-BY-FUNCTION

The GET-PRINT-BY-FUNCTION function is used to test whether there is any saved printer settings for the function/operator combination. These are saved using the SET-PRINT-BY-FUNCTION function.

For example you can allow the current printer settings to be stored against an invoice. Later you can restore these settings before you print the invoice.

This is part of the Printer per function facility.

Input parameters

LINK-PRINT-FUNCT

This is a 6 character field that defines the document to be used. It is recommended that codes beginning with USR are used by third parties to avoid possible conflict with standard codes.

Output parameters

LINK-EXTRA

If printer settings have been made against this function/operator combination then LINK-EXTRA contains the printer name. If blank then there is no saved printer settings for this function/operator combination.

Remarks

This function can be used as part of a user-interface to allow the operator to set/reset the printer settings for a function/operator combination.

The SET-PRINT-BY-FUNCTION is used to store these settings.

You can use the CLR-PRINT-BY-FUNCTION to remove the saved settings for the function/operator code.

The printer settings are stored in two C-ISAM files called ADMPRF.DAT and ADMPRH.DAT.

Sample code

*

** Test the current printer settings against document 'USRINV'

TEST-USRINV.

MOVE "USRINV" TO LINK-PRINT-FUNCT.

PERFORM GET-PRINT-BY-FUNCTION.

IF LINK-EXTRA = SPACES

MOVE LINK-EXTRA TO PRINTER-NAME-FOR-USRINV

ELSE

MOVE "{Undefined}" TO PRINTER-NAME-FOR-USERINV.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

Printer per function, PRINT-OPEN, PRINT-CLOSE, SET-PRINT-BY-FUNCTION, CLR-PRINT-BY-FUNCTION, RETRIEVE-PRINT-BY-FUNCTION


GET-STD-ENCORE-PATH

The GET-STD-ENCORE-PATH function is used to lookup one of the standard SYSPRO paths either on the server or client. These paths are mostly defined in IMPACT.INI on the appropriate system.

This routine is provided for compatibility with older versions of the software - please see the routine GET-STD-SYSPRO-PATH for details of this function.

See also

GET-STD-SYSPRO-PATH


GET-STD-SYSPRO-PATH

The GET-STD-SYSPRO-PATH function is used to lookup one of the standard SYSPRO paths either on the server or client. These paths are mostly defined in IMPACT.INI on the appropriate system.

This function is useful when you require to build a custom file name in one of the standard SYSPRO paths.

There is an identical routine called GET-STD-ENCORE-PATH provided for backward compatibility.

Input parameters

WW-FILE-NUM

This is a number indicating the path required.

Num .INI Description

1-9 IMPDT? Server - Data directories defined by IMPDT1 through IMPDT9

10 IMPPRG Server - Standard program directory

11 CUSPRG Server - Customized program directory

12 ------ Server - Base directory

13 IMPSNP Server - Snapshot directory for MRP

14 IMPTMP Server - Temporary directory

15 ------ Unused

16 IMPMCI Client - Multimedia directory

17 IMPGUI Server - Standard screenset directory

18 CUSGUI Server - Customized screenset directory

19 ------ Server - Working directory

20 IMPSTP Server - APS data directory (obsolete)

21 IMPGUI Client – Standard screenset directory

22 CUSGUI Client – Customized screenset directory

23 IMPTMP Client – Temporary directory

24 ------ Client - APS program directory (from client registry)

25 ------ Unused

The column headed .INI indicates the entry in IMPACT.INI.

Output parameters

WW-DIR-NAM

This is the returned path. It will have a trailing slash character appropriate for the operating system and will be surrounded in quotes if spacey.

WW-DIR-LEN

This is a pointer that points to the first free character after the trailing slash and any quotes.

Remarks

This function allows easy access to the most common SYSPRO paths.

Note that paths 21, 22 and 23 are all on the client in a client/server environment and have no relevance on a mapped drive system.

Note that paths 14 and 23 are both temporary paths and may not actually contain the IMPTMP= entries in the appropriate IMPACT.INI as they may have been overridden by a TEMP environment variable.

Note that the paths will be returned with quotes if it is a spacey file name. See the functions QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME for adding and removing quotes.

Sample code

* Build a path to 'report.txt' on the server's temp directory

MOVE 14 TO WW-FILE-NUM.

PERFORM GET-STD-ENORE-PATH.

MOVE WW-DIR-NAM TO FULL-TEMP-NAME.

MOVE "report.txt" TO FULL-TEMP-NAME(WW-DIR-LEN:).

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file name, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, IMPACT.INI


GET-WIP-TRIAL-LOCK-EXCLUSIVE

The GET-WIP-TRIAL-LOCK-EXCLUSIVE function is used to acquire a lock to process the WIP Trial loading file.

It is important to acquire a lock before changing the WIP Trail loading files. See the CLEAR-WIP-TRIAL-LOCK function.

Input parameters

LINK-EXTRA-2

If you wish to acquire a lock on a company other than the current company then move in the company id to this field.

Output parameters

LINK-EXTRA

A return status indicating whether the lock was acquired successfully.

Spaces – Lock acquired ok

Remarks

If you require to change the WIP trial load files then you should acquire a lock using this function.

Remember to clear the lock afterwards using CLEAR-WIP-TRIAL-LOCK.

Sample code

* Update WIP Trial Load

PERFORM GET-WIP-TRIAL-LOCK-EXCLUSIVE.

IF LINK-EXTRA = SPACES

PERFORM UPDATE-WIP-TRIAL-LOAD

ELSE

PERFORM UNABLE-TO-ACQUIRE-LOCK.

PERFORM CLEAR-WIP-TRIAL-LOCK.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

CLEAR-WIP-TRIAL-LOCK


HTML-TO-TEXT

The HTML-TO-TEXT function is used to translate HTML/XML format text that can contain character entities to plain text.

See the function TEXT-TO-HTML for translating plain text to HTML/XML format text.

Input parameters

WW-LINK-1

text in XML or HTML format. ie it can contain character entities.

Output parameters

WW-LINK-1

The plain text returned.

Remarks

This function is used to translate HTML/XML format text that can contain character entities to plain text.

The character entities supported are:

Character entity | Character
&lt; | <
&gt; | >
&amp; | &
&nbsp; | {space}
&#160; | {space}

Sample code

MOVE "Text &lt; and &gt; and &amp;" TO WW-LINK-1.

PERFORM HTML-TO-TEXT.

MOVE WW-LINK-1 TO PLAIN-TEXT.

Requirements

Version: Included in Encore 6.0 issue 007

Copybooks: Standard

See also

Well Formed XML, TEXT-TO-HTML


INCREMENT-LINE-X5

The INCREMENT-LINE-X5 function is used increment a 5 character alphanumeric line number.

This function is used in the General Ledger module where a 5 character alphanumeric line number has been used.

Input parameters

WW-LINE-X5

The initial value of the line number to be incremented.

May be '00000' - '99999' or 'AAAAA' - 'ZZZZZ'.

An initial value of spaces will be treated as '00000'

Output parameters

WW-LINE-X5

This field returns the initial value incremented by 1. See the Remarks for valid values.

WW-LINE-STAT

This field returns status information about the increment function.

Spaces - OK

O - Field overflow (exceeded 'ZZZZZ')

E - Invalid initial value

Remarks

This function is used by various General Ledger programs to manipulate an alphanumeric line number.

Background

The General Ledger system had 5 digit line numbers defined in various files. The line numbers were therefore limited to the values '00000' - '99999' (100,000 values).

An increase in the number of values was required but due to ISAM space limitations the 5 digit numeric line number has been changed to a 5 character alphanumeric line number for SYSPRO 6.0 issue 008.

The valid values are '00000' - '99999' (as before) plus 'AAAAA' - 'ZZZZZ'. This gives an additional 11,881,376 values. Therefore the total number of available line numbers is 11,981,376 (or approximately 12 million).

The new functions

Two new functions have been developed to allow developers to increment and decrement the 5 character alphanumeric line numbers. These are INCREMENT-LINE-X5 and DECREMENT-LINE-X5.

These new routines take the field WW-LINE-X5 and either increment or decrement the value according to the following logic:

- The valid values are '00000' - '99999' and 'AAAAA' - 'ZZZZZ'.

- When incrementing a value '00000' it will become '00001', then '00002', then '00003' etc.

- When incrementing a value '99999' it will become 'AAAAA'.

- Incrementing a value 'AAAAA' will return 'AAAAB', then 'AAAAC' etc.

- When incrementing 'ZZZZZ' you will receive an overflow error value 'O' in WW-LINE-STAT.

- If you pass a value outside the valid range you will receive an error value 'E' in WW-LINE-STAT.

- An initial value of spaces will be assumed to be '00000'.

The reverse logic is used when decrementing:

- 'ZZZZZ' will become 'ZZZZY', 'ZZZZY' will become 'ZZZZX' etc.

- 'AAAAA' will become '99999'.

- Decrementing '00000' will return the overflow (underflow) value 'O' in WW-LINE-STAT.

Remember when using these fields to store them as PIC X(5) - char(5) and also you should use care when displaying/printing these fields as they are alphanumeric fields.

Sample code

* Increment the next line number in GenMaster

MOVE GENMST-CNXT TO WW-LINE-X5.

PERFORM INCREMENT-LINE-X5.

IF WW-LINE-STAT = "O"

PERFORM MAX-LINE-NUMBER-EXCEEDED

ELSE

IF WW-LINE-STAT = "E"

PERFORM INVALID-LINE-NUMBER

ELSE

MOVE WW-LINE-X5 TO GENMST-CNXT.

Requirements

Version: Included in SYSPRO 6.0 issue 008 and later

Copybooks: standard

See also

DECREMENT-LINE-X5


INVOKE-MESSAGE-BOX

The INVOKE-MESSAGE-BOX function is used to display a message box allowing you to define the text, title, icon, the choice of buttons and the default button. You do not need to define any functions in a screenset for this to work.

There is a INVOKE-TASK-DIALOG function available from SYSPRO 6.1 that provides more sophisticated message box like functions.

Input parameters

LINK-EXTRA

The text to be displayed in the message box. Use line-feed characters (x"0a") to force line feeds. No other special characters should be used. Can be up to 600 characters.

LINK-MSG-HDG

The window title to be displayed. Can be up to 70 characters.

LINK-MSG-BUTTONS

A flag indicating which button combination is to be shown:

'1' – OK (default)

'2' – OK, Cancel

'3' – Yes, No

'4' – Retry, Cancel

'5' – Abort, Retry, Cancel

'6' – Yes, No, Cancel

'A' - OK (plus a 'Do not show this message again' checkbox)

'B' - OK, Cancel (plus a 'Do not show this message again' checkbox)

LINK-MSG-DEF

The default button

'1' – The first button (default)

'2' – The second button

'3' – The third button

LINK-MSG-ICON

'I' – Information (default)

'Q' – Question

'W' – Warning

'S' – Stop/Critical

LINK-MSG-CHK-PRG

A 6 character program name against which to store any 'Do not show this message again' preference.

LINK-MSG-CHK-BOX

A 6 character message box code against which to store any 'Do not show this message again' preference.

LINK-MSG-CHK-MSG

An optional 70 character message to be used instead of 'Do not show this message again'.

Output parameters

LINK-MSG-RETURN

This field indicates the button clicked by the operator - note that this is a numeric field

1 – OK

2 – Cancel

3 – Abort

4 – Retry

5 – Ignore

6 – Yes

7 – No

Remarks

This function is used to display a message box without using the dialog system. It works on both mapped and client/server systems (including Unix based systems).

Programmers will find this function particularly useful for displaying error and informational messages and can also be used during program development and to assist with debugging client/server systems.

The program IMPMSG is called to handle this function.

Note that there is a message box test harness program (SDKMSG) supplied as part of the software development kit that not only demonstrates all message box features but also allows you to view and animate the code used to generate message boxes.

If required you can use a line feed character x"0a" to force a new line to be inserted into the text. It is not recommended that you move any other special character into message box text.

Do not show this message again

If required you can have a 'Do not show this message again' checkbox added to the message box logic. This allows an operator to suppress this message for subsequent invocations of the message box.

To enable this function you move an A or B to the field LINK-MSG-BUTTONS. Then you must move spaces to the group field named LINK-MSG-CHK.

In addition you must move in a program name to LINK-MSG-CHK-PRG and a message box code to LINK-MSG-CHK-BOX. These two fields will be used, together with the operator code, to remember when this check box has been selected and will automatically suppress it from being shown in future.

You can override the default 'Do not show this message again' text by moving a string to the field LINK-MSG-CHK-MSG.

There is a function called INVOKE-MESSAGE-BOX-RESET that can be used to reset this saved setting - thus forcing the message box to be reshown the next time it is invoked.

Also note that an operator can now reset all their message box and task dialog warnings using the Personalize > Messages > Reset all Task Dialog Warnings button.

Icons

From SYSPRO 6.1 the native message boxes available in Windows are not used once you have logged into the SYSPRO menu. The message box parameters are converted to calls to a task dialog. However when this translation is performed any question mark icons are change to information icons.

Sample code

MOVE "Do you want to continue?" TO LINK-EXTRA.

MOVE "Option" TO LINK-MSG-HDG.

MOVE "2" TO LINK-MSG-BUTTONS. *> Ok, Cancel

MOVE "1" TO LINK-MSG-DEF. *> Default to OK

MOVE "Q" TO LINK-MSG-ICON. *> Question mark

PERFORM INVOKE-MESSAGE-BOX.

IF LINK-MSG-RETURN = 1 *> Ok selected

GO TO CONTINUE-FUNCTION.

Sample code showing use of default 'Do not show this message again'

MOVE "Do you want to continue?" TO LINK-EXTRA.

MOVE "Option" TO LINK-MSG-HDG.

MOVE "2" TO LINK-MSG-BUTTONS. *> Ok, Cancel

MOVE "1" TO LINK-MSG-DEF. *> Default to OK

MOVE "Q" TO LINK-MSG-ICON. *> Question mark

MOVE SPACES TO LINK-MSG-CHK. *> Initialize 'do not show this message again' values

MOVE "SDKMSG" TO LINK-MSG-CHK-PRG. *> Program name

MOVE "MSG001" TO LINK-MSG-CHK-BOX. *> Message box code

PERFORM INVOKE-MESSAGE-BOX.

IF LINK-MSG-RETURN = 1 *> Ok selected

GO TO CONTINUE-FUNCTION.

Requirements

Version: Included in SYSPRO 6.0 and later.

Copybooks: standard

See also

CALL-DS, INVOKE-MESSAGE-BOX-RESET, INVOKE-TASK-DIALOG


INVOKE-MESSAGE-BOX-RESET

The INVOKE-MESSAGE-BOX-RESET function is used to clear any saved preferences when an operator has clicked a 'Do not show this message again' checkbox when viewing a message invoked using the PERFORM INVOKE-MESSAGE-BOX or PERFORM INVOKE-TASK-DIALOG functions.

Also note that an operator can now reset all their message box and task dialog warnings using the Personalize > Messages > Reset all Task Dialog Warnings button.

Input parameters

LINK-MSG-CHK-PRG

The 6 character program name to be cleared of messages.

Spaces means all programs for the operator.

LINK-MSG-CHK-BOX

The 6 character message box code to be cleared of messages.

Spaces means all message boxes for the program.

Output parameters

none

Remarks

This function is used to reset message boxes that have previously been invoked with the 'Do not show this message again' checkbox.

This forces the message boxes to be reshown the next time they are invoked regardless of whether the operator clicked on the checkbox or not.

If required you can move spaces to the field LINK-MSG-CHK-PRG to cause all message boxes to be cleared for the current operator.

Similarly if a single program has several message box preferences then you can move the name of the program to LINK-MSG-CHK-PRG and clear all the message boxes for the program by moving spaces to the field LINK-MSG-CHK-BOX.

Note that this function is also used to reset task dialogs that have a 'Do not show this message again' checkbox. The program name and task dialog code is passed in exactly the same was as for message boxes.

Sample code

MOVE SPACES TO LINK-MSG-CHK. *> Initialize 'do not show this message again' values

MOVE "SDKMSG" TO LINK-MSG-CHK-PRG. *> Program name

MOVE "MSG001" TO LINK-MSG-CHK-BOX. *> Message box code

PERFORM INVOKE-MESSAGE-BOX-RESET.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

CALL-DS, INVOKE-MESSAGE-BOX, INVOKE-TASK-DIALOG


INVOKE-TASK-DIALOG

The INVOKE-TASK-DIALOG function is used to display a task dialog user interface element. This is a more sophisticated version of a message box.

Input parameters

STDTASK.WRK

You must include STDTASK.WRK in your working storage section to allow you to setup and pass parameters to the task dialog function.

Output parameters

STDTASK.WRK

The values in this copybook are used to determine the return values.

StdTaskDialogButton

This field contains the button value that was clicked. The exact values depend on whether a standard or user defined button was clicked.

StdTaskVerifyChecked

This field contains the value of the 'Do not show this message again' check box.

Remarks

This function is used to display a task dialog without using the dialog system. It works on both mapped and client/server systems (including Unix based systems).

Programmers will find this function particularly useful for displaying error and informational messages.

The older function INVOKE-MESSAGE-BOX is a subset of the task dialog functions and could be considered when the simpler parameters are suitable.

Note that there is a task dialog test harness program (SDKMSG) supplied as part of the software development kit that not only demonstrates most task dialog features but also allows you to view and animate the code used to generate task dialogs. It is recommended that you review the code in this program.

If required you can use a line feed character x"0a" to force a new line to be inserted into the text. It is not recommended that you move any other special character into text passed to the task dialog.

Overview of calling a task dialog

As there are a large number of parameters that can be passed to a task dialog we have described the parameters in a separate copybook called SDKTASK.WRK which must be defined in your working storage section.

To invoke a task dialog you should perform the following steps:

Initialize the field StdTaskDialogLink.

Move in the required text (heading, content, main, footer etc) and other parameters to the fields subordinate to StdTaskDialogLink. Most begin StdTask...

Call the task dialog function by using the following code fragment (it is best practice to use this code exactly as shown):

*

** Call Task Dialog

initialize ext-params.

move StdTaskDialogLink to ext-param-blob.

perform invoke-task-dialog.

move ext-param-blob to StdTaskDialogLink.

initialize ext-params. *> Must initialize fields when done

If there were more than a single button on the task dialog you require to check the value clicked. This is done by checking the field StdTaskDialogButton against one of the standard ID values defined in STDTASK.WRK or against one of the user defined buttons that you configured as an input parameter.

See the function show-task-dialog in the test harness SDKMSG.CBL for an example.

Do not show this message again

If required you can have a 'Do not show this message again' checkbox added to the task dialog. This allows an operator to suppress this message for subsequent invocations of the task dialog.

To enable this function you move a non zero value to the field StdTaskVerifyText.

In addition you must move in a program name to StdTaskVerifyProg and a task dialog code to StdTaskVerifyCode. These two fields will be used, together with the operator code, to remember when this check box has been selected and will automatically suppress it from being shown in future.

You can override the default 'Do not show this message again' text by moving a string to the field StdTaskVerifyText.

There is a function called INVOKE-MESSAGE-BOX-RESET that can be used to reset this saved setting - thus forcing the task dialog to be reshown the next time it is invoked.

Also note that an operator can now reset all their message box and task dialog warnings using the Personalize > Messages > Reset all Task Dialog Warnings button.

Language Translation

All text output to a task dialog will be automatically translated allowing it to be used in a multi language environment.

You should note that the maximum length of a phrase in the language translation system in 600 characters. Therefore if you are displaying a string that requires to be translated you should ensure that it stays within this limit.

If, however, you are showing information that does not require translation (for example a SQL Server statement being issued, or data from a file) then you can use the full 2000 characters in the field StdTaskContentText. In this case you should move a value of 1 to the field StdTaskNoTranContentText - this will prevent the system from attempting to translate the content and from truncating the Content Text.

Sample code

initialize StdTaskDialogLink.

move "Task Dialog Heading" to StdTaskWindowTitle.

move "This is a Task Dialog" to StdTaskMainText.

string

"This is the content text "

"against a task dialog and can "

"be formatted with line feed "

"characters."

x"0a0a"
"This is a new line." delimited by size

into StdTaskContentText.

move "This is the footer." to StdTaskFooterText.

*

move xtpTaskIconWarning to StdTaskMainIcon.

move xtpTaskIconInformation to StdTaskFooterIcon.

*

move 1 to StdTaskButton-OK. *> Ok button

move xtpTaskButtonOk to StdTaskDefButtonID. *> Default button id

*

** Call Task Dialog

initialize ext-params.

move StdTaskDialogLink to ext-param-blob.

perform invoke-task-dialog.

move ext-param-blob to StdTaskDialogLink.

initialize ext-params. *> Must initialize fields when done

*

if StdTaskDialogButton = xtpTaskButtonOk

perform button-ok-pressed

end-if.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard, STDTASK.WRK.

See also

INVOKE-MESSAGE-BOX


IS-DATE-VALID

The IS-DATE-VALID function is used to verify that a 6 digit date in the SYSPRO standard date format is a valid date.

Input parameters

DATE-NORMAL

A 6 digit date in the SYSPRO standard date format. One of

- DDMMYY

- MMDDYY

- YYMMDD

Output parameters

DATE-VALID

A flag indicating that the date in DATE-NORMAL is valid.

Y – Yes

Remarks

Date formats requested from the screen are usually held in a 6 digit SYSPRO standard date format. This is determined by the System setup option. It can be one of:

- DDMMYY

- MMDDYY

- YYMMDD

This routine is used to verify that the date is valid. Leap years in the date range are fully supported.

Note that dates stored in this format can be in the range:

1st Jan 1950 through 31st Jan 2049

Dates stored in a file or a SYSPRO database are always defined as CCYYMMDD format regardless of the setting described above. To swap between these date formats use DATE-TO-CYMD and DATE-FROM-CYMD.

To swap dates from the 6 digit SYSPRO standard date format and a YYMMDD format use DATE-YMD and DATE-NORM.

Sample code

MOVE D-ASK-DATE TO DATE-NORMAL.

PERFORM IS-DATE-VALID.

IF DATE-VALID = "Y"

GO TO DATE-IS-VALID-ROUTINE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

DATE-TO-CYMD, DATE-FROM-CYMD, DATE-YMD, DATE-NORM, NUMB-CHECK, Date ageing functions


IS-DATE-VALID-CYMD

The IS-DATE-VALID-CYMD function is used to verify that a CCYYMMDD format date is a valid date.

Input parameters

DATE-CCYYMMDD

A date in CCYYMMDD format.

Output parameters

DATE-VALID

A flag indicating that the date in DATE-CCYYMMDD is valid.

Y – Yes

Remarks

Dates stored in a file or a SYSPRO database are stored in CCYYMMDD format.

This routine is used to verify that a date stored in this format is valid. Leap years in the date range are fully supported.

Note that dates stored in this format can be in the range:

1st Jan 1900 through 31st Jan 2099

To verify that a date is valid in the SYSPRO standard date format use IS-DATE-VALID.

Sample code

MOVE 20021231 TO DATE-CCYYMMDD.

PERFORM IS-DATE-VALID-CYMD.

IF DATE-VALID = "Y"

GO TO DATE-IS-VALID-ROUTINE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

IS-DATE-VALID, Date ageing functions


IS-LEAP-YEAR

The IS-LEAP-YEAR function is used to verify that a 4 digit year is a leap year and also to return the number of days in February for the selected year.

Input parameters

WW-LEAP-YEAR

A 4 digit year.

Output parameters

WW-LEAP-FLAG

A flag indicating whether the year provided is a leap year or not.

1 - Leap year

WW-LEAP-FEB

The number of days in February for the year provided (either 28 or 29).

Remarks

This function simply requires a 4 digit year to be provided and returns a flag indicating if the year is a leap year or not and also how many days there are in February for the year provided.

This routine should be used rather than any calculation or lookup table being hard-coded.

Sample code

MOVE YEAR-CCYY TO WW-LEAP-YEAR.

PERFORM IS-LEAP-YEAR.

IF WW-LEAP-FLAG = 1

PERFORM LEAP-YEAR-LOGIC

ELSE

PERFORM NON-LEAP-YEAR-LOGIC

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later

Copybooks: standard

See also

Date ageing functions, IS-DATE-VALID, IS-DATE-VALID-CYMD


JOB-MESSAGE

The JOB-MESSAGE function updates the message field against the job logging file for this program. This allows a program to save a message in the job logging file so that an administrator can review what has happened.

The Job log file is company based. If you wish to output information to the System Audit log file that is system-wide consider the function OUTPUT-SYSTEM-JOB-LOG.

Input parameters

WW-JOBLOG-MSG

A 40 character message to be inserted into the job logging file.

Output parameters

none

Remarks

Each program has a single 40 character message that can be posted against the job log when required. If this function is called more than once then only the last message will be saved.

Job logging is enabled/disabled against the Company setup program. This function has no effect unless job logging is enabled for the company.

Note that Transaction Processing functions (BEGIN-TRANSACTION and COMMIT-TRANSACTION) also use this 40 character message field. Therefore you should consider using the JOB-MESSAGE-DETAIL function.

The JOB-MESSAGE-DETAIL function allows multiple 60 character messages to be output to the job logging detail file. This is the preferred function for outputting messages.

Sample code

MOVE "Inventory Month-end" TO WW-JOBLOG-MSG.

PERFORM JOB-MESSAGE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: Standard

See also

JOB-MESSAGE-IF-BLANK, JOB-MESSAGE-READ, JOB-MESSAGE-TRANSACT, JOB-MESSAGE-DETAIL, OUTPUT-SYSTEM-JOB-LOG


JOB-MESSAGE-DETAIL

The JOB-MESSAGE-DETAIL function inserts a new detail message against the job logging detail file for the current program. You can output multiple messages for a single run of the program.

The Job log file is company based. If you wish to output information to the System Audit log file that is system-wide consider the function OUTPUT-SYSTEM-JOB-LOG.

Input parameters

WW-JOBDET-MSG

A 60 character message to be inserted into the job logging detail file.

Output parameters

none

Remarks

This function allows a program to insert multiple messages into the job logging detail file. This can be used to indicate the progress of a program or to indicate what options were selected, or any other information that the programmer requires to be output.

The job logging detail records the date and time that the message was inserted.

When viewing job logging you can 'zoom' into the detail. In addition the job logging detail will appear on the Job logging report.

Job logging is enabled/disabled against the Company setup program. This function has no effect unless job logging is enabled for the company.

Sample code

MOVE "Inventory Purge started" TO WW-JOBDET-MSG.

PERFORM JOB-MESSAGE-DETAIL.

*

PERFORM INVENTORY-PURGE-FUNCTION.

*

MOVE "Inventory Purge completed" TO WW-JOBDET-MSG.

PERFORM JOB-MESSAGE-DETAIL.

Requirements

Version: Included in SYSPRO 6.0 issue 007 and later

Copybooks: Standard

See also

JOB-MESSAGE, JOB-MESSAGE-IF-BLANK, JOB-MESSAGE-READ, JOB-MESSAGE-TRANSACT, OUTPUT-SYSTEM-JOB-LOG


JOB-MESSAGE-IF-BLANK

The JOB-MESSAGE-IF-BLANK function updates the message field against the job logging file for this program. This allows a program to save a message in the job logging file so that an administrator can review what has happened.

If there is already an existing message for this program then this function does nothing.

Input parameters

WW-JOBLOG-MSG

A 40 character message to be inserted into the job logging file.

Output parameters

none

Remarks

Each program has a single 40 character message that can be posted against the job log when required. If this function is called and a message already exists then the new message will not overwrite the existing message - nothing is done.

To force a message, regardless of whether there is one or not, use the JOB-MESSAGE function.

Job logging is enabled/disabled against the Company setup program. This function has no effect unless job logging is enabled for the company.

Sample code

MOVE "Process started" TO WW-JOBLOG-MSG.

PERFORM JOB-MESSAGE-IF-BLANK.

Requirements

Version: Included in Encore 5.1 issue 004 later

Copybooks: Standard

See also

JOB-MESSAGE, JOB-MESSAGE-READ, JOB-MESSAGE-TRANSACT


JOB-MESSAGE-READ

The JOB-MESSAGE-READ function reads and returns the message field against the job logging file for this program.

Input parameters

none

Output parameters

WW-JOBLOG-MSG

This field contains the current value of the message field in the job log file.

Remarks

Each program has a single 40 character message that can be posted against the job log when required. This function allow a program to read the current value of the message for the current program.

To set a message use the JOB-MESSAGE function.

Job logging is enabled/disabled against the Company setup program. This function has no effect unless job logging is enabled for the company.

Sample code

PERFORM JOB-MESSAGE-READ.

IF WW-JOBLOG-MSG = "Process started"

MOVE "Process finished" TO WW-JOBLOG-MSG

PERFORM JOB-MESSAGE.

Requirements

Version: Included in Encore 5.1 issue 004 later

Copybooks: Standard

See also

JOB-MESSAGE, JOB-MESSAGE-IF-BLANK, JOB-MESSAGE-TRANSACT


JOB-MESSAGE-TRANSACT

The JOB-MESSAGE-TRANSACT function is used internally by other standard functions. These are the transaction processing functions. It is not recommended that you use this function directly.

Input parameters

WW-JOBLOG-MSG

A 40 character message to be inserted into the job logging file.

LINK-SQL-TRAN-STAT

Transaction status

Output parameters

none

Remarks

This function is used internally and should not be used directly by user programs.

Sample code

Not applicable

Requirements

Version: Included in Encore 5.0 and later

Copybooks: Standard

See also

Transaction Processing


LOOK-UP-ERROR

The LOOK-UP-ERROR function is used to return a language independent message given a message number. It is used for common messages such as file handling messages. These messages are generally short - less than 80 characters.

Input parameters

WW-ERROR-NUM

An error message number

Output parameters

WW-ERROR-MSG and D-S-ERROR

The message returned.

Remarks

This function is used to return messages from the IMPMSG.IMP file located in the program directory.

If you want the message on line x then move the value x - 1 to WW-ERROR-NUM. For example to read the message at line 201 move 200 to WW-ERROR-NUM.

If you have set your LANG environment variable (on the client in a client/server environment) to a two digit language code then the file used will be IMPMSGxx.IMP where xx is the language code.

Note that most messages are now defined using the LOOKUP-MSG function - this function is likely to be updated in the future to use the LOOKUP-MSG style for messages.

Note that prior to SYSPRO 6.1 the file containing the message was named IMPACT.ERR.

Sample code

MOVE 200 TO WW-ERROR-NUM.

PERFORM LOOK-UP-ERROR.

MOVE WW-ERROR-NUM TO NOT-ON-FILE-MESSAGE-TEXT.

Requirements

Version: Included in Encore 5.0 and later. File name accessed changed for SYSPRO 6.1.

Copybooks: standard

See also

LOOKUP-MSG


LOOKUP-MSG

The LOOKUP-MSG function is used to return a language independent message given a message number. It is used for almost all messages used in SYSPRO and e.net. These messages can be up to 600 characters long and may be parameterized.

Input parameters

LINK-COM-MSG

A 6 digit message number - See ???STD.WRK files for 78 levels defining valid numbers.

LINK-EXTRA

A value to replace optional parameter %1

LINK-EXTRA-2

A value to replace optional parameter %2

LINK-EXTRA-3

A value to replace optional parameter %3

Output parameters

LINK-EXTRA

The message returned.

Remarks

This function is used to return messages from the message files stored in the program directory. See the topic Error Handling for the file names and set numbers used.

Each standard message has a 78 level field defining the message number to be used. These numbers are 6 digit numbers consisting of a 2 digit set number and a 4 digit message number. The set number is used to group messages. Note that certain set numbers are reserved for future use. See the working storage copybooks ???STD.WRK for the 78 level numbers.

Some messages require between 1 and 3 optional parameters represented by %1, %2 and %3. When these parameters are defined in a message you must pass their values in the appropriate LINK-EXTRA fields - See Input parameters above.

If you have set your LANG environment variable (on the client in a client/server environment) to a two digit language code then this will be used - otherwise the language code defined against the operator will be used.

Sample code

MOVE COM-MSG-INV-STK-NOT TO LINK-COM-MSG. *> Stock code '%1' not found

MOVE STOCK-CODE TO LINK-EXTRA.

PERFORM LOOKUP-MSG.

MOVE LINK-EXTRA TO MESSAGE-TEXT.

Requirements

Version: Included in Encore 5.1 issue 005 and later

Copybooks: standard

See also

Error Handling, LOOK-UP-ERROR, COM-ERROR-MSG


MODULE-NOT-INSTALLED

The MODULE-NOT-INSTALLED function is used to display a message indicating that the license for the company does not include this module.

Input parameters

none

Output parameters

none

Remarks

Important programs in each module test the setting of the module installed flags. If the appropriate module is not installed then this function should be called.

Flags that should be tested include:

IM0CRE Accounts Payable

IM0DEB Accounts Receivable

IM0CSH Cash Book

IM0GEN General Ledger

IM0PLN Assets Register

IM0INV Inventory Control

IM0SOS Purchase Orders

IM0SAL Sales Analysis

IM0ORD Sales Orders

IM0PRO Bill of Materials

IM0EST Estimating/Quotations

IM0DOC Factory Documentation

IM0NET Requirements Planning

IM0-ECC Engineering Change control

IM0-REP Report Writer

IM50-S-ABC Activity Based Costing

IM50-S-CFG Product Configurator

IM50-S-LCT Landed Cost Tracking

IM50-S-PRJ Projects and Contracts

IM50-S-CTR Counter Sales

IM50-S-CUM Blanket Purchase orders and Releases

Sample code

* This Inventory program check if Inventory is installed

IF IM0INV NOT = "Y"

PERFORM MODULE-NOT-INSTALLED

GO TO ENDJOB.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard


MULTIMEDIA-DELETE-ALL

The MULTIMEDIA-DELETE-ALL function is designed to delete all multimedia objects for a key.

Multimedia objects are a flexible and consistent way of defining and using objects such as bitmaps, sound clips, videos or in fact any OLE2 linked object.

Developers can define Multimedia objects against any field.

Input parameters

LINK-EXTRA-2

This is a 6 character multimedia type indicating the category of object to be deleted. Existing standard multimedia types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Multimedia objects should use types beginning with USR. See ADMMMA.MAC for a more complete list of standard types.

LINK-BROWSE

This is the key field of the item to be deleted. For example for multimedia type STK this is the stock code.

Output parameters

none

Remarks

This function is used to delete a single all multimedia objects for a key field.

Most of the Multimedia functions can be accessed directly from a screenset using the S-M functions (S-MPLAY, S-MEDIT, S-MDEL etc).

Sample code

* Delete all multimedia objects against a stock code 'B100'

MOVE "STK" TO LINK-EXTRA-2. *> Multimedia type

MOVE "B100" TO LINK-BROWSE. *> Stock code

PERFORM MULTIMEDIA-DELETE-ALL.

Requirements

Version: Included in Encore 5.1 issue 004 and later.

Copybooks: standard

See also

Multimedia, MULTIMEDIA-PLAY, MULTIMEDIA-GET-PATH


MULTIMEDIA-GET-PATH

The MULTIMEDIA-GET-PATH function is designed to retrieve the path to an existing multimedia object for a key.

Multimedia objects are a flexible and consistent way of defining and using objects such as bitmaps, sound clips, videos or in fact any OLE2 linked object.

Developers can define Multimedia objects against any field.

Input parameters

LINK-EXTRA-2

This is a 6 character multimedia type indicating the category of object to be accessed. Existing standard multimedia types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Multimedia objects should use types beginning with USR. See ADMMMA.MAC for a more complete list of standard types.

LINK-EXTRA-3

This is a 3 character multimedia object. The multimedia object is configured from within SYSPRO. It is a 3 character mnemonic to help identify the type of object being defined. For example when defining bitmaps you may use BMP. This does not have to be the file extension in use but it often makes it easier to understand if it is.

LINK-BROWSE

This is the key field of the item to be retrieved. For example for multimedia type STK this is the stock code.

Output parameters

LINK-EXTRA

The path to the multimedia object is returned in this field.

Remarks

This function is used to retrieve the path to an existing multimedia object for a key. For example the path to a bitmap could be returned.

If you just wish to play/show the multimedia object use the MULTIMEDIA-PLAY function.

Most of the Multimedia functions can be accessed directly from a screenset using the S-M functions (S-MPLAY, S-MEDIT, S-MDEL etc).

Sample code

* retrieve the path to the JPG multimedia object against a stock code 'B100'

MOVE "STK" TO LINK-EXTRA-2. *> Multimedia type

MOVE "JPG" TO LINK-EXTRA-3. *> Multimedia object

MOVE "B100" TO LINK-BROWSE. *> Stock code

PERFORM MULTIMEDIA-GET-PATH.

MOVE LINK-EXTRA TO JPEG-PATH-NAME.

MOVE SPACES TO LINK-EXTRA.

Requirements

Version: Included in Encore 5.1 issue 004 and later.

Copybooks: standard

See also

Multimedia, MULTIMEDIA-PLAY, MULTIMEDIA-DELETE-ALL


MULTIMEDIA-PLAY

The MULTIMEDIA-PLAY function is designed to play/show the multimedia object for a key.

Multimedia objects are a flexible and consistent way of defining and using objects such as bitmaps, sound clips, videos or in fact any OLE2 linked object.

Developers can define Multimedia objects against any field.

Input parameters

LINK-EXTRA-2

This is a 6 character multimedia type indicating the category of object to be accessed. Existing standard multimedia types include:

CUS | Customers
SUP | Suppliers
STK | Stock codes
LDG | Ledger codes
ORD | Sales orders
PORD | Purchase orders
JOB | Jobs

Third party developers defining their own Multimedia objects should use types beginning with USR. See ADMMMA.MAC for a more complete list of standard types.

LINK-EXTRA-3

This is a 3 character multimedia object. The multimedia object is configured from within SYSPRO. It is a 3 character mnemonic to help identify the type of object being defined. For example when defining bitmaps you may use BMP. This does not have to be the file extension in use but it often makes it easier to understand if it is.

LINK-BROWSE

This is the key field of the item to be played/shown. For example for multimedia type STK this is the stock code.

Output parameters

none

Remarks

This function is used to play/show the multimedia object defined against a key field.

If you just wish to see the name of the multimedia object use the MULTIMEDIA-GET-PATH function.

Most of the Multimedia functions can be accessed directly from a screenset using the S-M functions (S-MPLAY, S-MEDIT, S-MDEL etc).

Sample code

* Show any JPG multimedia object against a stock code 'B100'

MOVE "STK" TO LINK-EXTRA-2. *> Multimedia type

MOVE "JPG" TO LINK-EXTRA-3. *> Multimedia object

MOVE "B100" TO LINK-BROWSE. *> Stock code

PERFORM MULTIMEDIA-PLAY.

Requirements

Version: Included in Encore 5.1 issue 004 and later.

Copybooks: standard

See also

Multimedia, MULTIMEDIA-GET-PATH, MULTIMEDIA-DELETE-ALL


NULL-TASK

The NULL-TASK function can be used by a very long running process to prevent a timeout on a client/server system.

Generally long running tasks should provide a tickover or status display so that the operator can see that the process is running successfully. If a program takes more than an hour for a function and does not call the screenset at least once in this time the client process will timeout causing a program failure.

The NULL-TASK function can be called occasionally to prevent this timeout.

Input parameters

none

Output parameters

none

Remarks

This function is only required and only does anything on a client/server system.

The NULL-TASK function calls the client process running on the client computer which immediately returns. Although the amount of network traffic generated by this function is low you should avoid performing it frequently as this can slow the server process noticeably. Remember the purpose of this function is to prevent the timeout that occurs after one hour with no call to the screenset.

It is recommended that the program is re-coded to use a tickover function to indicate more frequently the program status.

Sample code

PERFORM NULL-TASK.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

TICKOVER


NULL-TERMINATE-STRING

The NULL-TERMINATE-STRING function is used to ensure that a string has a null terminator.

When interfacing to Win32 API functions - and other languages - string values are often null terminated. This function simplifies this process. Note that trailing spaces are ignored.

Input parameters

WW-LINK-1

The string to be null terminated – current maximum of 1000 characters.

Output parameters

WW-LINK-1

The null terminated string.

NULX1

Pointer to the null character

Remarks

This routine simplifies generating null terminated strings.

When calling Win32 API functions you typically require a null terminated string.

Warning - if your initial string has exactly 1000 characters then the null character will be inserted at character position 1000. i.e. the last character will be lost.

Note that if a program literal is required this can be defined in Net Express using the z character before the string. This avoids the requirement for this function.

For example:

MOVE z"This will be null terminated" TO NULL-TERMINATED-STRING.

Sample code

* Call a message box using the Win32 API

* Demonstrates the use of NULL-TERMINATE-STRING and the

* Net Express z"string" functions

SHOW-MESSAGE-BOX.

MOVE "This is the message box text" TO WW-LINK-1.

PERFORM NULL-TERMINATE-STRING.

MOVE WW-LINK-1 TO MBOX-TEXT.

*

call Win32 'MessageBoxA'

using by value 0 size 4 *> Window handle

by reference MBOX-TEXT *> Null terminated text

by reference z"Message Box" *> Null terminated title

by value 8208 size 4. *> OK and Info icon

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard


NUMB-CHECK

The NUMB-CHECK function is used to verify a free format alphanumeric field contains a valid numeric value. In addition the value is returned in an easy-to-use format and the number of integers, decimals and whether the value is signed is also returned. This is commonly used when verifying numeric values in import files.

Input parameters

NUMB-R

A 30 character alphanumeric field that can contain a numeric value.

Output parameters

NUM-VAL

The returned signed value with up to 12 integers and 6 decimal places. This is generally the returned value to be used when NUM-OK is Y.

NUM

This is a 15 digit integer value. Typically this is used when requesting a numeric stock code which can be up to 15 digits.

NUM-OK

A flag indicating that the input field contains valid numeric editing characters. These include the digits 0-9 a minus sign (-) and a decimal point (.) in addition any thousands separators such as ',' or spaces will be ignored from the input field. All other characters are invalid.

If the input field contains decimals and there are > 12 integers or > 6 decimals then NUM-OK will be set to N.

If the input field contains integers only (no decimals) and there are > 15 integers then NUM-OK will be set to N

NUM-INT

This is a numeric field indicating the number of integers found.

NUM-DEC

This is a numeric field indicating the number of decimal places found.

Remarks

This routine is generally used when receiving alphanumeric fields from other applications.

This routine always uses a decimal point '.' - commas and spaces are ignored from the input parameter.

It is also used when formatting an entered key that can be alpha or numeric depending on the Company setup options. For example when requesting a customer code the program will accept a 7 character alphanumeric field. However if the customer code is defined as numeric it is the programmers responsibility to format the entered customer code into a 7 digit numeric value. NUMB-CHECK is commonly used for this task.

Sample code

* Validate customer code accepted as alphanumeric

MOVE D-ASK-CUSTOMER-ALPHA-7 TO NUMB-R.

PERFORM NUMB-CHECK.

IF NUM-OK = "Y"

MOVE NUM-VAL TO CUSTOMER-CODE-NUM-7

ELSE

GO TO INVALID-NUMERIC-CUSTOMER.

* Verify a value max 12.2

MOVE D-ENTERED-VALUE-ALPHA TO NUMB-R.

PERFORM NUMB-CHECK.

IF NUM-INT > 12

MOVE "Greater than 12 integers found" TO D-S-ERROR

ELSE

IF NUM-DEC > 2

MOVE "Greater that 2 decimals found" TO D-S-ERROR

ELSE

IF NUM-OK <> "Y"

MOVE "Invalid character in numeric field" TO D-S-ERROR

ELSE

MOVE NUM-VAL TO D-VALUE-OK.

Requirements

Version: Included in Encore 5.0 and later. SYSPRO 6.0 Issue 007 contains additional logic to return the number of integers and decimals greater that 12 and 6 respectively.

Copybooks: standard

See also

IS-DATE-VALID, IS-DATE-VALID-CYMD


OBJECT-COUNT-END

The OBJECT-COUNT-END function is a developer aid to help ensure that there are minimal or no memory leaks when using various Net Express data objects such as character arrays, ordered collections, sorted collections and dictionaries.

If you are not using any of these data objects then you do not require to use this function.

See the function OBJECT-COUNT-START for a detailed description about how to use this function.

Input parameters

OBJ-COUNT-EXTRA

The number of 'acceptable' memory leaks - will default to zero

also

Must have included CLASS.WRK in your source code.

Must have previously used the OBJECT-COUNT-START function.

Output parameters

OBJ-COUNT-LEAK

Number of objects over-and-above that saved when using OBJECT-COUNT-START

Remarks

See the function OBJECT-COUNT-START for a detailed description about how to use this function.

Sample code

FILE-CONTROL.

COPY "ADMREP.SEL".

COPY "CLASS.WRK".

.

*

DATA DIVISION.

FILE SECTION.

< rest of code >

** Check for memory leaks

PERFORM OBJECT-COUNT-START.

PERFORM SOME-CODE. *> Code to be tested

PERFORM OBJECT-COUNT-END. *> Displays warning if diagnostic is 'leak01' or 'leak02'

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard and must also include CLASS.WRK

See also

OBJECT-COUNT-START


OBJECT-COUNT-START

The OBJECT-COUNT-START function is a developer aid to help ensure that there are minimal or no memory leaks when using various Net Express data objects such as character arrays, ordered collections, sorted collections and dictionaries.

If you are not using any of these data objects then you do not require to use this function.

Input parameters

none

Must have included CLASS.WRK in your source code.

Output parameters

OBJ-COUNT-START

Number of objects in use.

Remarks

When you use Net Express data objects such as character arrays, ordered collections, sorted collections and dictionaries you should be aware that they can consume arbitrary amounts of memory and, unlike regular fields defined as PIC fields in WORKING STORAGE, it is your responsibility to ensure that there are no (or only minimal) memory leaks during the run of your application.

The Developers section of the SYSPRO Support Zone documents how to use these data objects using the sample program (SDK004.CBL) provided as part of the Software Development Kit.

However it can be useful to verify how many data objects are being consumed and even to verify that you have finalized all objects appropriately.

The functions OBJECT-COUNT-START and OBJECT-COUNT-END can be used for this purpose.

How do I use these functions?

These functions require you to have inserted the copybook CLASS.WRK into your source code as shown from the following code fragment from SDK004.CBL.

FILE-CONTROL.

*

COPY "INVMST.SEL".

COPY "ADMREP.SEL".

*

COPY "CLASS.WRK".

.

*

DATA DIVISION.

FILE SECTION.

Note that the line highlighted in blue contains the CLASS-CONTROL definitions and that there is a line immediately below the CLASS.WRK copybook that consists of only a dot. You must have this line (just containing a dot) for the program to compile cleanly. The reason for this is that the CLASS.WRK copybook does not terminate the CLASS-CONTROL clause allowing you to add your own sub-clauses if required. However the dot is required to correctly conclude the CLASS-CONTROL clause.

Important - the CLASS.WRK copybook contains a constant CLASS-WRK-FLG that is used in PROBEGIN.PRO to determine whether the OBJECT-COUNT-START and OBJECT-COUNT-END functions can work as expected. If CLASS.WRK is not defined in your source code then the OBJECT-COUNT-END function will always return that there are no memory leaks (even if there are).

Surround your code to be tested for memory leaks with the OBJECT-COUNT-START and OBJECT-COUNT-END functions. See the following code fragment:

PERFORM OBJECT-COUNT-START.

PERFORM SOME-CODE. *> Code to be tested

PERFORM OBJECT-COUNT-END.

The OBJECT-COUNT-START function counts the current number of objects in use (by SYSPRO as a whole) and stores the value in the field OBJ-COUNT-START.

The OBJECT-COUNT-END function also counts the number of objects and compares the two values. the field OBJ-COUNT-LEAK contains the number of additional objects.

If required you can setup a maximum number of memory leaks that is acceptable in OBJ-COUNT-EXTRA - this value defaults to zero.

If OBJ-COUNT-LEAK is greater that the number of 'acceptable' leaks then a message box is displayed indicating the number of memory leaks detected.

Note that as these memory leak functions are only designed to be used in a development environment the message is suppressed by default. To enable the memory leak message box you should set your Diagnostic value to 'leak01' or 'leak02' using the System Setup program in SYSPRO.

Notes about memory leaks

The Dialog system and other user interface elements (such as list views and toolbars) consume memory objects and will not necessarily finalize them during the run of SYSPRO - therefore you should avoid counting the number of objects and then calling the dialog system and checking for leaks as this will always return a leak.

It's worth noting that even if your program has memory leaks these will be restored when you exit SYSPRO. The real issue with memory leaks is to avoid continually consuming memory without finalizing it correctly - especially when you have a program or function can be invoked many times without SYSPRO being exited.

Sample code

FILE-CONTROL.

COPY "ADMREP.SEL".

COPY "CLASS.WRK".

.

*

DATA DIVISION.

FILE SECTION.

< rest of code >

** Check for memory leaks

PERFORM OBJECT-COUNT-START.

PERFORM SOME-CODE. *> Code to be tested

PERFORM OBJECT-COUNT-END. *> Displays warning if diagnostic is 'leak01' or 'leak02'

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard and must also include CLASS.WRK

See also

OBJECT-COUNT-END


OUTPUT-DEBUG-LOG

The OUTPUT-DEBUG-LOG function is designed to allow developers to easily debug programs that are failing or to time long running processes.

The developer can move in any message to LINK-EXTRA to indicate the progress and then perform this function. A file will be created/appended that contains the current operating system date and time together with the text message.

Input parameters

LINK-EXTRA

This is a text message to indicate the progress of the program.

Output parameters

none

Remarks

The log file created by this function resides beneath the base directory (on the server in a client/server environment) called SETTINGS\{operator}.TXT where {operator} is your operator code. For example when logging in as ADMIN the file will be called

SETTINGS\ADMIN.TXT

Note on a Unix server environment the log file is written directly to the base folder.

If this file does not exists it will be created. If it already exists then it will be appended. The file is closed between calls so that you do not get sharing violations using operating system commands to view the file. It is recommended that you do not output to the debug file using the same operator code at the same time as this may cause conflicts in writing to the log file.

Note that if your program is already using LINK-EXTRA then you may need to save and restore it to avoid changing the program logic.

This function is purely to assist developers in debugging their programs. There are two types of programs that this function can assist with.

  1. Long running tasks that you want to improve or change in some way

  2. Programs that do not run as expected or crash inexplicably – this is a special problem in a client/server environment where any Net Express Run Time System error messages may be lost.

Long running tasks

Every time you call this function a line is created with the date and time together with your message. By outputting messages as each phase or part of your process is starting you can later review the total time and the elapsed time between each message. This can be saved and later compared with an improved version of the program.

Unexpected crashes

If your program seems to crash or fails unexpectedly it can be difficult to find where it is failing – especially in a client/server environment.

The best way to narrow down the problem is to move in an appropriate message and call this function when the program first loads. Then do the same thing when it exists (at ENDJOB). Then add various other messages between these two points.

By running the program you can check that your program is loading correctly (ie the initial message has been created). You can also check what was the last message before the crash occurs. If the last message is shown (the one at ENDJOB) then it's possible that it is another program that is causing the problem.

When testing your program multiple times it is advisable to delete this log file between sessions as it may be confusing.

Note that on Windows NT/2000 based systems where SYSPRO is running as a service then see the System Event Viewier - Application log. Messages logged with Micro Focus COBOL will contain any Run Time System messages.

Note that on Unix systems a file called server.log contains any Net Express Run Time System messages. You should look at this file if you get unexpected crashes on Unix systems.

Note for more help with debugging Unix specific issues see the topic Debugging on Unix.

Sample code

* Output message to log file

MOVE "Program loaded" TO LINK-EXTRA.

PERFORM OUTPUT-DEBUG-LOG.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Debugging on Unix, ENDJOB


OUTPUT-SYSTEM-JOB-LOG

The OUTPUT-SYSTEM-JOB-LOG function is designed to allow developers to add entries to the System Audit log.

Each entry written to the System Audit log is assigned a category. The available categories are defined in IMPJNS.IMP (and custom ones in CUSJNS.IMP).

Input parameters

LINK-EXTRA-1

Up to 60 character description of System Audit entry

LINK-EXTRA-2

System Audit log category

Output parameters

none

Remarks

This function is used by developers to write entries to the System Audit log. This log is designed to store system-wide logging information. Note that company based logging information is typically stored in the company job log file - see functions JOB-MESSAGE and JOB-MESSAGE-DETAIL.

System Audit log information typically provides information about security breaches, notification of operator, group, role and password changes, when operators have been logged out and by whom. Also supervisor password changes, workflow overrides, system options and other serious changes to the system are also logged in this file.

You should not typically use the System Audit log to record regular and/or frequent transactional information. It is not intended that the System Audit log is populated with significant information in a short space of time.

Before you perform the OUTPUT-SYSTEM-JOB-LOG function you should move a 60 character description to LINK-EXTRA-1. In addition you should move the relevant category to LINK-EXTRA-2. See below.

System Audit log categories

The available System Audit log categories are defined in the file IMPJNS.IMP (stored in the program folder). This contains a list of the available categories together with their descriptions. The System Audit viewer program (IMPJNS) provides a category filter allowing you to select transactions for a specific category.

SYSPRO developers typically add new categories to IMPJNS.IMP.

Third party developers should add new categories to the custom file CUSJNS.IMP.

Sample code

* Output message to System Audit file when operator

* is logged out of SYSPRO

MOVE SPACES TO LINK-EXTRA.

STRING

"Operator '" DELIMITED BY SIZE

OPERATOR-NAME DELIMITED BY " "

"'" DELIMITED BY SIZE

INTO LINK-EXTRA-1.

MOVE "LOG-DEL" TO LINK-EXTRA-2. *> Std Category

PERFORM OUTPUT-SYSTEM-JOB-LOG.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

JOB-MESSAGE, JOB-MESSAGE-DETAIL


PRINT-BOLD-OFF

The PRINT-BOLD-OFF function is used to reset bold that has been set by the PRINT-BOLD-ON function.

This function forms part of the generic Printing functions that provide a simple and consistent way of printing to any of the different printer types supported.

The programmer must use PRINT-OPEN to initialise the generic printer functions, any number of text lines can be written to the report. Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

Input parameters

none

Output parameters

none

Remarks

The PRINT-BOLD-ON function is used by the programmer to switch on bold for one or more lines.

Note that currently bold attributes affect an entire line. It is not possible to bold a column or characters only.

Sample code

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

PERFORM PRINT-BOLD-ON.

MOVE "Second line of text in bold" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

PERFORM PRINT-BOLD-OFF.

*

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV, PRINT-BOLD-ON


PRINT-BOLD-ON

The PRINT-BOLD-ON function is used to allow subsequent lines to be output in bold. Use PRINT-BOLD-OFF to clear the bold printing – also note that the HOF function clears this bold setting. This only has an effect when printing to a Windows printer.

This function forms part of the generic Printing functions that provide a simple and consistent way of printing to any of the different printer types supported.

The programmer must use PRINT-OPEN to initialise the generic printer functions, any number of text lines can be written to the report. Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

Input parameters

none

Output parameters

none

Remarks

Remember to issue a PRINT-OPEN function before trying to print any text using the generic print routines. After printing you must finalise the report with the PRINT-CLOSE function.

See the PRINT-OPEN function for details of the different types of printer supported and other information including how the line count is maintained.

Remember to use PRINT-BOLD-OFF to switch bold printing off.

Note that currently bold attributes affect an entire line. It is not possible to bold a column or characters only.

To print a line of text move the text to the field SP-PRLINE and then use WRITE-PRLINE-AFTER-1. This performs a single line skip (from the current/previous line) and then prints the current line of text. There are additional functions WRITE-PRLINE-AFTER-2, WRITE-PRLINE-AFTER-3 etc up to 9.

In addition you can move the number of lines to be skipped to the field SP-LINE-SKIP and the use WRITE-PRLINE-AFTER-SKIP.

The function WRITE-PRLINE-AFTER-PAGE should be used to force a page skip before printing the line of text.

Sample code

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

PERFORM PRINT-BOLD-ON.

MOVE "Second line of text in bold" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

PERFORM PRINT-BOLD-OFF.

*

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, WRITE-PRLINE-AFTER-SKIP, WRITE-PRLINE-AFTER-PAGE, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV, PRINT-BOLD-OFF


PRINT-CLOSE

The PRINT-CLOSE function is used to finalise a report or document and must be issued to initiate a screen preview and/or actual printing of the document.

See the Printing overview for more details about printing.

Input parameters

none

Output parameters

none

Remarks

PRINT-CLOSE must be used to finalise a report.

Generally this starts the actual printing/previewing of the report. Most report programs include this is the ENDJOB paragraph.

Once the PRINT-CLOSE function has been performed the program can start a new PRINT-OPEN function.

If you need to abort a print job and close the printer without printing anything (rare) then you should use PRINT-CLOSE-NO-PRINT which will return system resources.

You can force the report preview to be created in a view-only mode (disallowing Print, Email and Copy to clipboard functions) by moving VIEWONLY to LINK-EXTRA prior to using PRINT-CLOSE. when using this feature you must also move Y to L-PRT-PREVIEW before using the PRINT-OPEN function.

Sample code

MOVE "Demonstration report" TO L-PRT-TITLE.

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

Printing, PRINT-OPEN, PRINT-CLOSE-NO-PRINT


PRINT-CLOSE-NO-PRINT

The PRINT-CLOSE-NO-PRINT function is used to finalise a report and ensure that the document is not printed. This is used in the rare case where a program must abort the current print job and print nothing.

See the Printing overview for more details about printing.

Input parameters

none

Output parameters

none

Remarks

This function is used in place of PRINT-CLOSE.

Once this function has been performed you can issue a PRINT-OPEN function.

Sample code

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE-NO-PRINT. *> Abort without printing

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

Printing, PRINT-OPEN, PRINT-CLOSE


PRINT-HOF-UNDERLINE

The PRINT-HOF-UNDERLINE function is used to clear the bold setting and draw a heading underline and should only be used after issuing the WRITE-PRLINE-AFTER-PAGE function outside of a HOF routine.

Input parameters

none

Output parameters

none

Remarks

See the description against WRITE-PRLINE-AFTER-PAGE for more details.

Sample code

HEAD-OF-FORM-SPECIAL.

MOVE SP-PAGE-COUNT TO PRPAGE.

MOVE "Y" TO SP-HOF-BOLD.

MOVE HDG1 TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

MOVE HDG2 TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

PERFORM PRINT-HOF-UNDERLINE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-PAGE, PRINT-CLOSE


PRINT-HORIZONTAL-LINE

The PRINT-HORIZONTAL-LINE function is used to print a horizontal line across the page. This is often used to separate groups of items – for example customers sorted by branch.

When printing to a Windows printer a thin solid line is printed, all other types of printer uses a line of dashes (---) to represent the horizontal line. This function uses one character height spacing.

This function forms part of the generic Printing functions that provide a simple and consistent way of printing to any of the different printer types supported.

The programmer must use PRINT-OPEN to initialise the generic printer functions, any number of text lines can be written to the report. Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

Input parameters

none

Output parameters

none

Remarks

Remember to issue a PRINT-OPEN function before trying to print any text using the generic print routines. After printing you must finalise the report with the PRINT-CLOSE function.

See the PRINT-OPEN function for details of the different types of printer supported and other information including how the line count is maintained.

To print a line of text move the text to the field SP-PRLINE and then use WRITE-PRLINE-AFTER-1. This performs a single line skip (from the current/previous line) and then prints the current line of text. There are additional functions WRITE-PRLINE-AFTER-2, WRITE-PRLINE-AFTER-3 etc up to 9.

In addition you can move the number of lines to be skipped to the field SP-LINE-SKIP and the use WRITE-PRLINE-AFTER-SKIP.

The function WRITE-PRLINE-AFTER-PAGE should be used to force a page skip before printing the line of text.

Sample code

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

PERFORM PRINT-HORIZONTAL-LINE.

*

MOVE "Third line of text – below line" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, WRITE-PRLINE-AFTER-SKIP, WRITE-PRLINE-AFTER-PAGE, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


PRINT-OPEN

The PRINT-OPEN function is used to initialise the print functions. This must be done before printing any text. The generic Printing functions provide a simple and consistent way of printing to any of the different printer types supported.

Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

See the topic Printing Overview for more details of this and other printing architectures.

Input parameters

L-PRT

The general linkage fields defined at the group level by L-PRT in LINK.WRK are used to configure the printer settings. It is not recommended to change any of these settings, except using the standard SYSPRO programs and functions provided as they are subject to change.

L-PRT-TITLE

This is a 40 character report title. This is shown in the title bar of the screen preview and on the Windows printer spooler window. This is useful when many reports have been spooled to a printer – especially when you want to cancel one of them.

L-WIN-BMP

For Windows printers this allows you to define a bitmap to be printed as a background to every page in the report. Only Windows .bmp format files are supported. You should define the width of the bitmap (see below) to ensure the text is always exactly aligned. The aspect ratio of the bitmap is retained.

L-WIN-BMP-SMET

This field defines whether the width of the bitmap is defined in inches or millimetres.

i – inches

m – millimetres

L-WIN-BMP-SFAC

This field defines the printed width of the bitmap (in either inches or millimetres).

L-WIN-EML-F

This field is a flag to indicate that a default email address has been passed and that this should be the default email address when previewing a report and the operator clicks on the E-Mail… push button.

L-WIN-EMAIL

This is the email address to be used as the default – See L-WIN-EML-F above.

L-PRT-PREVIEW

You can force a preview of a report (rather than just printing it) by moving Y to this field. In addition you can force the report preview to be created in a view-only mode (disallowing Print, Email and Copy to clipboard functions) by moving VIEWONLY to LINK-EXTRA prior to using PRINT-CLOSE.

L-PRT-DELETE

This field can be set to N to prevent the printer system from removing the temporary spooled report when it has finished. See the article Printing and Retaining a Spooled Report for more information.

LINK-PRT-HANDLE

You can move a window handle to this field to force the Windows Print dialog to become a child of your window or dialog box ensuring that the Windows print dialog remains in the foreground.

CHECK-DEF-PRT-PROG

You can move a 6 character program name to be used to determine which program's settings are to be used. Spaces means the current printer.

Output parameters

L-PRT-FILENAME

This field contains the name of the temporary spooled report that was used in the printing/preview. On a client/server system this is the temporary spooled report that resides on the server.

Remarks

Use this function to initialise the printer system before it is used. This must be done within each program that requires to print. See the Printing overview for a list of the facilities available.

Printer types supported include:

  • Windows printers – native Windows printer support

  • Device printer – writes 'raw' data to a device such as LPT1: or a UNC name such as \\server\printer

  • Disk file – stores the report on a disk file – can be printed later

  • Spooler (temporary file) – this printer type spools the report to a disk file and you can then define any operating system command or program to process this file

  • Spooler (Unix) – this is a Unix Server specific type of printing that can directly interface with the Unix spooler system

There are many printer settings can be setup by the operator. These include:

  • Printer type (Windows, Device, Disk file, Spooler)

  • Paper size

  • Orientation

  • Margins

  • Font and point size

  • Preview on/off

  • Request print dialog before each report

  • Number of copies

Not all settings are supported by all printer types.

You can force the report preview to be created in a view-only mode (disallowing Print, Email and Copy to clipboard functions) by moving VIEWONLY to LINK-EXTRA prior to using PRINT-CLOSE. when using this feature you must also move Y to L-PRT-PREVIEW before using the PRINT-OPEN function.

Shift+F8

An operator can press Shift+F8 when running any program that prints a report. This allows the operator to assign a default printer (and other settings) for that program so that subsequent printing of the report at a later date will use the saved printer settings. This information is stored per operator per program.

The Shift+F8 code is handled automatically by the SYSPRO printing architecture. However there may be cases where your program calls another program to print the actual report. In this case when performing the PRINT-OPEN function the code should check another program for the Shift+F8 function and not the current one.

This can be managed by moving the 'other' program name to the field CHECK-DEF-PRT-PROG before using the PRINT-OPEN function. This field will be cleared once used - reverting back to spaces - which means the current program.

Sample code

MOVE "Demonstration report" TO L-PRT-TITLE.

MOVE D-S-WINHAN TO LINK-PRT-HANDLE. *> Must be setup in dialog

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later. The ability to include a default email address is only available in Encore 5.1 issue 003 and later. The ability to call the preview in a view-only mode is only available in Encore 5.1 issue 005 and later. The ability to prevent removing the temporary spooled report file is only available in SYSPRO 6.0 issue 009 port 03 and later. The ability to pass a window handle to force the Print dialog box to stay in foreground is only available in SYSPRO 6.0 issue 009 port 12 and later. The function to allow a different default printer to be selected is only available from SYSPRO 6.0 issue 010 and later.

Copybooks: standard

See also

Printing, Print offsets, Printing and Retaining a Spooled Report, WRITE-PRLINE-AFTER-1, WRITE-PRLINE-AFTER-SKIP, WRITE-PRLINE-AFTER-PAGE, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


PROCESS-WW-LOGIC-TAB

The PROCESS-WW-LOGIC-TAB function is used to evaluate a table of True/False and And/Or boolean values. Up to 10 levels of nested brackets are supported.

Input parameters

WW-LOGIC-TAB

A table of up to 150 characters of True/False And/Or and bracket values to be evaluated.

Output parameters

WW-LOGIC-RESULT

A flag indicating the evaluation of the input table. Values are:

T - True

F - False

E - Error

WW-LOGIC-MSG

If the logic result was 'E' (Error) then this field contains a message explaining the problem.

Remarks

This function evaluates a string of True/False and And/Or flags using boolean logic to generate a True or False result.

Up to 10 levels of nested brackets are supported.

'And' logic takes precedence over 'Or' logic at the same level of brackets.

The following boolean logic truth table is supported.

Value 1 | Logic | Value 2 | Result
False | AND | False | False
False | AND | True | False
True | AND | False | False
True | AND | True | True
False | OR | False | False
False | OR | True | True
True | OR | False | True
True | OR | True | True

The following characters are supported in the input string.

Character | Meaning
T | True
F | False
A | AND
O | OR
( | Open bracket
) | Close bracket

The table below shows some worked examples.

Input string | Result | Notes
T | T - True | Simple evaluation
F | F - False | Simple evaluation
TOF | T - True | Uses 'OR' truth table
TAF | F - False | Uses 'AND' truth table
TA(TOF) | T - True | The brackets are evaluated first and 'TOF' is 'True'... This then leaves 'TAT' which is also 'True'.

The sample program SDKTRU demonstrates use of this function.

Note that invalid characters or incorrect levels of brackets will result in an Error condition being generated together with an explanatory message.

Sample code

* Evaluate logic and return message

MOVE "TA(TOF)" TO WW-LOGIC-TAB. *> Example logic

PERFORM PROCESS-WW-LOGIC-TAB.

MOVE SPACES TO D-MSG.

EVALUATE WW-LOGIC-RESULT

WHEN "T"

MOVE "The result is True" TO D-MSG

WHEN "F"

MOVE "The result is False" TO D-MSG

WHEN "E"

MOVE WW-LOGIC-MSG TO D-MSG

END-EVALUATE.

Requirements

Version: Included in SYSPRO 6.0 issue 009 port 16 and later.

Copybooks: standard

See also

CONVERT-ASCII-TO-HEX, CONVERT-HEX-TO-ASCII


QUIT-DS

The QUIT-DS function is used by every program that calls a screenset to remove the screenset from the dialog system screenset stack. Generally this is inserted at the end of the program in the ENDJOB routine.

Input parameters

none

Output parameters

none

Remarks

Every program that calls a screenset must perform this function must before it exits. This ensures that the current screenset is removed from memory and the focus is set on the previous screenset.

If a program has not called a screenset then this function has no effect.

The dialog system control block field DSG-CONTROL is used to indicate whether a screenset is being shown.

Sample code

ENDJOB.

PERFORM QUIT-DS.

EXIT PROGRAM.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

CALL-DS, QUIT-DS-ALWAYS, ENDJOB


QUIT-DS-ALWAYS

The QUIT-DS-ALWAYS function is an internal routine that is called by the QUIT-DS routine. Generally you should not have to call this function.

Input parameters

none

Output parameters

DSG-CONTROL

Spaces indicating that the screenset has been popped from the dialog system screenset stack.

Remarks

This routine must not be called unless the screenset was successfully loaded into the dialog system. Rather use QUIT-DS.

Sample code

ENDJOB.

PERFORM QUIT-DS.

EXIT PROGRAM.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

CALL-DS, QUIT-DS


QUOTE-VALID-FILE-NAME

The QUOTE-VALID-FILE-NAME function is used to ensure that a spacey file name is surrounded with quotes. This is required with most Net Express and C-ISAM functions such as opening a file, checking if it exists and deleting it.

Input parameters

WW-FILE-NAME

The file name to be quoted if spacey.

Output parameters

WW-FILE-NAME

File name in a format that can be used by Net Express. If spacey then it will have quotes if not spacey then it is not changed.

Remarks

A spacey file name must be quoted when using any C-ISAM functions and when using various standard calls such as CHECK-FILE-EXISTS and DELETE-WW-FILE-NAME. This call has no effect on non-spacey file names.

Note that Win32 API calls must not have quoted file names – see STRIP-VALID-FILE-NAME.

Sample code

MOVE "C:\Documents and Settings\File.txt" TO WW-FILE-NAME.

PERFORM QUOTE-VALID-FILE-NAME.

MOVE WW-FILE-NAME TO QUOTED-FILE-NAME.

This results in "C:\Documents and Settings\File.txt" in QUOTED-FILE-NAME.

Requirements

Version: Included in Encore 5.0 issue 007 and Encore 5.1 issue 003 and later

Copybooks: Standard

See also

spacey file name, STRIP-VALID-FILE-NAME


READ-COMPANY-PATHS

The READ-COMPANY-PATHS function is used by programs that require to build file names for companies other than the currently logged in company.

The reason for this function is that the data directories may be different from one company to another. This function initialises the build file name routines so that subsequent file names will be built using the correct parameters.

It is important to ensure that the original company settings are restored before the program exits. This is done using the same function with the original company id.

Input parameters

WW-COMPID

This contains the company id (0-9, A-Z) of the required company.

Output parameters

none

Remarks

A system administrator can define one or more directories to be used for data files within a company. The simplest is to have all files stored in the same directory for all companies, however it may be required to separate one companies files from another or alternatively to place large files (such as history or transaction files) on a separate drive.

There is a company specific C-ISAM file that defines the location of each file for that company. When building data files names the current companies locations are used.

This function is typically used when accessing data files from another company – for example for inter-company postings.

After calling this function all subsequent calls to the build file name functions use the passed company id.

Important note: it is important to restore the original companies settings. Failure to do this may result in subsequent programs accessing data from the wrong location.

Sample code

* Build and open customer file from current company

PERFORM ARSMST-BUILD-AND-OPEN-IO-COMER.

PERFORM CUSTOMER-PROCESSING.

PERFORM ARSMST-CLOSE.

* Build and open customer file from another company

MOVE COMPID TO ORIGINAL-COMPID.

MOVE ANOTHER-COMPID TO WW-COMPID.

PERFORM READ-COMPANY-PATHS.

*

PERFORM ARSMST-BUILD-AND-OPEN-IO-COMER.

PERFORM CUSTOMER-PROCESSING.

PERFORM ARSMST-CLOSE.

* Restore company paths…

MOVE ORIGINAL-COMPID TO WW-COMPID.

PERFORM READ-COMPANY-PATHS.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

BUILD-FILE-NAME


REFRESH-SECURITY-SETTINGS

The REFRESH-SECURITY-SETTINGS function is used by programs when they require to take account of the current operator code, role and company.

This is typically performed for you automatically when you login or switch roles. However you can force the system to take account of the current settings at any time.

Input parameters

OPERATOR-CODE

This contains the current operator code.

OPERATOR-ROLE

This contains the current operator role.

COMPID

This contains the current company id.

Output parameters

none

Remarks

The REFRESH-SECURITY-SETTINGS function is used by programs when they require to take account of the current operator code, role and company.

This is typically performed for you automatically when you login or switch roles. However you can force the system to take account of the current settings at any time. This could be used, for example, after calling the program access maintenance program or operator maintenance.

This ensures that the following areas are refreshed:

- eSignatures

- Program access

- Activities

- Fields

- Access control (warehouse, branch etc.)

Sample code

* Refresh the latest security settings

PERFORM REFRESH-SECURITY-SETTINGS.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

BUILD-FILE-NAME


REGISTER-MSG

The REGISTER-MSG function is used by report programs to allow headings and other fixed messages to be translated before they are printed.

When the program initially loads the REGISTER-MESSAGES function (a mandatory function in SYSPRO programs) can be used to move message strings into a field and call the REGISTER-MSG function. This will lookup any translation and return the translated value back to the same field. The program can then use this returned value on the report.

Each message string to be translated must be assigned a 6 character key. This is unique to the program. The program name and unique key form the index to the translation file. It is recommended that once a key has been assigned that it is not changed. This ensures that any translation made is retained in future.

A language code can be defined against a group of operators. An administrator can view all the messages used by a report and translate them using the Customization, Report Text Translation function

Input parameters

WW-TRAN-MSG

The message text to be translated should be moved to this field. Up to 300 characters can be used.

WW-TRAN-KEY

This is a 6 character unique code to identify the string.

Output parameters

WW-TRAN-MSG

The returned translated message.

Remarks

The Language code is a two digit numeric code defined against the operator group. If this code is defined then whenever a report program is loaded it is the responsibility of the program to pass all headings and message text through this function to ensure that they are translated appropriately.

The administrator can use the Customization, Report Text Translation program from the main menu to view and translate the text for all programs using this function.

Each message string to be translated must be assigned a 6 character key. This is unique to the program. The program name and unique key form the index to the translation file. It is recommended that once a key has been assigned that it is not changed. This ensures that any translation made is retained in future.

The translated text is stored in an ISAM file in the working directory and is called ENCOREnn.DAT where nn is the two digit language code. On Unix based systems the file is called ENCOREnn.

Some common language codes are:

05 English

07 French

12 Spanish

It is highly recommended that when using English that the default language code (none) is used. If you use 05 English this causes all reports to use the translation functions unnecessarily.

Sample code

REGISTER-MESSAGES.

MOVE "HDG1" TO WW-TRAN-KEY.

MOVE HDG1 TO WW-TRAN-MSG.

PERFORM REGISTER-MSG.

MOVE WW-TRAN-MSG TO HDG1.

*

MOVE "HDG2" TO WW-TRAN-KEY.

MOVE HDG2 TO WW-TRAN-MSG.

PERFORM REGISTER-MSG.

MOVE WW-TRAN-MSG TO HDG2.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE


RESET-TICKOVER

The RESET-TICKOVER function is used by a program that is using either the TICKOVER or SERV functions to indicate that the very next time one of these calls is issued that they should immediately call the screenset regardless of the tickover settings defined against the operator.

Input parameters

None

Output parameters

None

Remarks

See TICKOVER and SERV functions for an explanation of the RESET-TICKOVER function.

Sample code

PERFORM RESET-TICKOVER.

MOVE INVMST-STK TO D-TICKOVER.

PERFORM TICKOVER.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

TICKOVER, SERV


RESOURCE-LOCK-ADD

The RESOURCE-LOCK-ADD function is used to acquire a resource lock.

See the topic Resource Locking for a description of resource locks and how they should be used.

Input parameters

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

When you initialized WW-LOCK-FIELDS this company field will be set to spaces which indicates the 'current' company id. This has been done as this is by far the most common requirement. However you can move in a specific company required.

Move LOW-VALUES to this company field to indicate that you require a system-wide resource lock.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

This could be the name of the program or any other string that uniquely identifies the resource to be locked.

Note that as the field is 10 characters long you could use a combination of program or file name and a short string.

It is recommended that third party developers prefix their codes with a hyphen ('-') as none of the standard codes used by SYSPRO applications start with a hyphen.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

In the example of the alternate stock code maintenance it would be logical to use the parent stock code being maintained as the key field.

If you have the situation where there is no 'key' then you can just move in the same code as moved to the field WW-LOCK-TYP. This field may not be left blank.

WW-LOCK-DES (mandatory)

This specifies a mandatory 40 character description of the type of resource being locked.

In the example of the alternate stock code maintenance it would be logical to use a description 'Alternate stock codes'.

The resource lock description is useful for administrators viewing the resource lock table. In addition when another user attempts to lock exactly the same company, type, key that you have locked they will see the resource lock description in any message displayed.

Because of these reasons it is highly recommended that you use a friendly description of the resource lock type.

WW-LOCK-FLG (optional)

This specifies an optional 1 character flag that applies to the specific resource being locked.

When another user attempts to lock exactly the same company, type, key that you have locked, the program that they are using can detect this and either display a standard task dialog or the application can retrieve this flag (and any optional reference - see below) and use this for further action or display a custom message. This could be used to further describe the resource being locked.

WW-LOCK-REF (optional)

This specifies an optional 60 character reference that applies to the specific resource being locked.

When another user attempts to lock exactly the same company, type, key that you have locked, the program that they are using can detect this and either display a standard task dialog or the application can retrieve this reference (and any optional flag - see above) and use this for further action or display a custom message. This could be used to further describe the resource being locked.

Output parameters

STAT-LCK

Logical value set if the resource is locked. See sample code below.

WW-LOCK-DES

The description of the resource lock.

WW-LOCK-OPR

The operator code showing who acquired the lock.

WW-LOCK-NAM

The operator name showing who acquired the lock.

WW-LOCK-DAT

The date that the lock was acquired in CCYYMMDD format.

WW-LOCK-TIM

The time that the lock was acquired in HHMMSSFF format (where FF means 1/100ths of a second).

WW-LOCK-REF

The optional reference against the resource lock.

WW-LOCK-FLG

The optional flag against the resource lock.

Remarks

When you wish to acquire a resource lock you must initialize the group field named WW-LOCK-FIELDS and then populate the input fields as applicable.

Note that in most cases this just requires the type, key and description fields to be setup.

When you use the RESOURCE-LOCK-ADD function to acquire a new lock it can return a STAT-LCK status indicating that the resource is already locked by someone else. In this case the output fields are returned.

Note that there is an equivalent function called RESOURCE-LOCK-ADD-MSG that will display a standard task dialog if the resource is already locked - this saves you from having to display your own message. The same 'STAT-LCK' status is returned as if you had used the RESOURCE-LOCK-ADD function.

Important - when you have finished with the resource it is best practice to remove the lock using RESOURCE-LOCK-DELETE.

Sample code

* Acquire an 'alternate stock code' lock

* If locked then show operator code and name

INITIALIZE WW-LOCK-FIELDS.

MOVE D-COMPID TO WW-LOCK-COM.

MOVE "INVPAL" TO WW-LOCK-TYP.

MOVE D-ENT-STOCK TO WW-LOCK-KEY.

MOVE "Alternate stock code" TO WW-LOCK-DES.

PERFORM RESOURCE-LOCK-ADD.

IF STAT-LCK

STRING

"Locked by '" DELIMITED BY SIZE

WW-LOCK-OPR DELIMITED BY " "

" - " DELIMITED BY SIZE

WW-LOCK-NAM DELIMITED BY " "

"'." DELIMITED BY SIZE

INTO D-LOCKED-MESSAGE

ELSE

MOVE SPACES TO D-LOCKED-MESSAGE

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

Resource Locking, RESOURCE-LOCK-ADD-MSG, RESOURCE-LOCK-DELETE


RESOURCE-LOCK-ADD-MSG

The RESOURCE-LOCK-ADD-MSG function is used to acquire a resource lock and display a message if the resource is already locked by someone else.

See the topic Resource Locking for a description of resource locks and how they should be used.

Input parameters

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

When you initialized WW-LOCK-FIELDS this company field will be set to spaces which indicates the 'current' company id. This has been done as this is by far the most common requirement. However you can move in a specific company required.

Move LOW-VALUES to this company field to indicate that you require a system-wide resource lock.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

This could be the name of the program or any other string that uniquely identifies the resource to be locked.

Note that as the field is 10 characters long you could use a combination of program or file name and a short string.

It is recommended that third party developers prefix their codes with a hyphen ('-') as none of the standard codes used by SYSPRO applications start with a hyphen.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

In the example of the alternate stock code maintenance it would be logical to use the parent stock code being maintained as the key field.

If you have the situation where there is no 'key' then you can just move in the same code as moved to the field WW-LOCK-TYP. This field may not be left blank.

WW-LOCK-DES (mandatory)

This specifies a mandatory 40 character description of the type of resource being locked.

In the example of the alternate stock code maintenance it would be logical to use a description 'Alternate stock codes'.

The resource lock description is useful for administrators viewing the resource lock table. In addition when another user attempts to lock exactly the same company, type, key that you have locked they will see the resource lock description in any message displayed.

Because of these reasons it is highly recommended that you use a friendly description of the resource lock type.

WW-LOCK-FLG (optional)

This specifies an optional 1 character flag that applies to the specific resource being locked.

When another user attempts to lock exactly the same company, type, key that you have locked, the program that they are using can detect this and either display a standard task dialog or the application can retrieve this flag (and any optional reference - see below) and use this for further action or display a custom message. This could be used to further describe the resource being locked.

WW-LOCK-REF (optional)

This specifies an optional 60 character reference that applies to the specific resource being locked.

When another user attempts to lock exactly the same company, type, key that you have locked, the program that they are using can detect this and either display a standard task dialog or the application can retrieve this reference (and any optional flag - see above) and use this for further action or display a custom message. This could be used to further describe the resource being locked.

Output parameters

STAT-LCK

Logical value set if the resource is locked. See sample code below.

WW-LOCK-DES

The description of the resource lock.

WW-LOCK-OPR

The operator code showing who acquired the lock.

WW-LOCK-NAM

The operator name showing who acquired the lock.

WW-LOCK-DAT

The date that the lock was acquired in CCYYMMDD format.

WW-LOCK-TIM

The time that the lock was acquired in HHMMSSFF format (where FF means 1/100ths of a second).

WW-LOCK-REF

The optional reference against the resource lock.

WW-LOCK-FLG

The optional flag against the resource lock.

Remarks

When you wish to acquire a resource lock you must initialize the group field named WW-LOCK-FIELDS and then populate the input fields as applicable.

Note that in most cases this just requires the type, key and description fields to be setup.

When you use the RESOURCE-LOCK-ADD-MSG function to acquire a new lock it can return a STAT-LCK status indicating that the resource is already locked by someone else. In this case a task dialog is displayed and the output fields are returned.

Note that there is an equivalent function called RESOURCE-LOCK-ADD that also returns the same fields and flags as this function except that it does NOT display any task dialog. You can use this to handle the fact that a resource is locked by someone else yourself.

Important - when you have finished with the resource it is best practice to remove the lock using RESOURCE-LOCK-DELETE.

Sample code

* Acquire an 'alternate stock code' lock

* An automatic message is shown if it is already locked

INITIALIZE WW-LOCK-FIELDS.

MOVE D-COMPID TO WW-LOCK-COM.

MOVE "INVPAL" TO WW-LOCK-TYP.

MOVE D-ENT-STOCK TO WW-LOCK-KEY.

MOVE "Alternate stock code" TO WW-LOCK-DES.

PERFORM RESOURCE-LOCK-ADD-MSG.

IF STAT-LCK

MOVE "L" TO D-LOCK-FLAG

ELSE

MOVE "Y" TO D-LOCK-FLAG

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

Resource Locking, RESOURCE-LOCK-ADD, RESOURCE-LOCK-DELETE


RESOURCE-LOCK-DELETE

The RESOURCE-LOCK-DELETE function is used to delete an existing resource lock that you previously acquired.

See the topic Resource Locking for a description of resource locks and how they should be used.

Input parameters

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

When you initialized WW-LOCK-FIELDS this company field will be set to spaces which indicates the 'current' company id. This has been done as this is by far the most common requirement. However you can move in a specific company required.

Move LOW-VALUES to this company field to indicate that you require a system-wide resource lock.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

This could be the name of the program or any other string that uniquely identifies the resource to be locked.

Note that as the field is 10 characters long you could use a combination of program or file name and a short string.

It is recommended that third party developers prefix their codes with a hyphen ('-') as none of the standard codes used by SYSPRO applications start with a hyphen.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

In the example of the alternate stock code maintenance it would be logical to use the parent stock code being maintained as the key field.

If you have the situation where there is no 'key' then you can just move in the same code as moved to the field WW-LOCK-TYP. This field may not be left blank.

Output parameters

STAT-LCK

Logical value set if the resource is locked. See sample code below.

WW-LOCK-DES

The description of the resource lock.

WW-LOCK-OPR

The operator code showing who acquired the lock.

WW-LOCK-NAM

The operator name showing who acquired the lock.

WW-LOCK-DAT

The date that the lock was acquired in CCYYMMDD format.

WW-LOCK-TIM

The time that the lock was acquired in HHMMSSFF format (where FF means 1/100ths of a second).

WW-LOCK-REF

The optional reference against the resource lock.

WW-LOCK-FLG

The optional flag against the resource lock.

Remarks

You should use this function to delete any previously acquired resource lock.

When you wish to delete a resource lock you must initialize the group field named WW-LOCK-FIELDS and then populate the input fields as applicable.

Note that in most cases this just requires the type and key fields to be setup.

When you use the RESOURCE-LOCK-DELETE function to test for a resource lock it can return a STAT-LCK status indicating that the resource is already locked by someone else. In this case the output fields are returned and the existing lock is NOT deleted. You cannot delete a lock held by someone else.

It is recommended that when you add a lock using the RESOURCE-LOCK-ADD or RESOURCE-LOCK-ADD-MSG functions that you set a flag so that you can be sure to remove the lock when you have finished with the resource. It's also a good idea to add this test in the ENDJOB paragraph to ensure that you do not retain a resource lock even if a program terminates abnormally.

Sample code

* Delete a previously acquired 'alternate stock code' lock

INITIALIZE WW-LOCK-FIELDS.

MOVE D-COMPID TO WW-LOCK-COM.

MOVE "INVPAL" TO WW-LOCK-TYP.

MOVE D-LAST-STOCK TO WW-LOCK-KEY.

PERFORM RESOURCE-LOCK-DELETE.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

Resource Locking, RESOURCE-LOCK-ADD, RESOURCE-LOCK-ADD-MSG, RESOURCE-LOCK-TEST-MSG, RESOURCE-LOCK-DELETE


RESOURCE-LOCK-TEST

The RESOURCE-LOCK-TEST function is used to test whether a resource lock exists.

See the topic Resource Locking for a description of resource locks and how they should be used.

Input parameters

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

When you initialized WW-LOCK-FIELDS this company field will be set to spaces which indicates the 'current' company id. This has been done as this is by far the most common requirement. However you can move in a specific company required.

Move LOW-VALUES to this company field to indicate that you require a system-wide resource lock.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

This could be the name of the program or any other string that uniquely identifies the resource to be locked.

Note that as the field is 10 characters long you could use a combination of program or file name and a short string.

It is recommended that third party developers prefix their codes with a hyphen ('-') as none of the standard codes used by SYSPRO applications start with a hyphen.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

In the example of the alternate stock code maintenance it would be logical to use the parent stock code being maintained as the key field.

If you have the situation where there is no 'key' then you can just move in the same code as moved to the field WW-LOCK-TYP. This field may not be left blank.

Output parameters

STAT-LCK

Logical value set if the resource is locked. See sample code below.

WW-LOCK-DES

The description of the resource lock.

WW-LOCK-OPR

The operator code showing who acquired the lock.

WW-LOCK-NAM

The operator name showing who acquired the lock.

WW-LOCK-DAT

The date that the lock was acquired in CCYYMMDD format.

WW-LOCK-TIM

The time that the lock was acquired in HHMMSSFF format (where FF means 1/100ths of a second).

WW-LOCK-REF

The optional reference against the resource lock.

WW-LOCK-FLG

The optional flag against the resource lock.

Remarks

You can use this function to test whether a resource lock has been acquired by another user.

When you wish to test for a resource lock you must initialize the group field named WW-LOCK-FIELDS and then populate the input fields as applicable.

Note that in most cases this just requires the type and key fields to be setup.

When you use the RESOURCE-LOCK-TEST function to test for a resource lock it can return a STAT-LCK status indicating that the resource is already locked by someone else. In this case the output fields are returned.

Note that there is an equivalent function called RESOURCE-LOCK-TEST-MSG that will display a standard task dialog if the resource is already locked - this saves you from having to display your own message. The same 'STAT-LCK' status is returned as if you had used the RESOURCE-LOCK-TEST function.

Important - when you have finished with the resource it is best practice to remove the lock using RESOURCE-LOCK-DELETE.

Sample code

* Test for an 'alternate stock code' lock

* If locked then show operator code and name

INITIALIZE WW-LOCK-FIELDS.

MOVE D-COMPID TO WW-LOCK-COM.

MOVE "INVPAL" TO WW-LOCK-TYP.

MOVE D-ENT-STOCK TO WW-LOCK-KEY.

PERFORM RESOURCE-LOCK-TEST.

IF STAT-LCK

STRING

"Locked by '" DELIMITED BY SIZE

WW-LOCK-OPR DELIMITED BY " "

" - " DELIMITED BY SIZE

WW-LOCK-NAM DELIMITED BY " "

"'." DELIMITED BY SIZE

INTO D-LOCKED-MESSAGE

ELSE

MOVE SPACES TO D-LOCKED-MESSAGE

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

Resource Locking, RESOURCE-LOCK-TEST-MSG, RESOURCE-LOCK-DELETE


RESOURCE-LOCK-TEST-MSG

The RESOURCE-LOCK-TEST-MSG function is used to test whether a resource lock exists and display a message if the resource is already locked by someone else.

See the topic Resource Locking for a description of resource locks and how they should be used.

Input parameters

WW-LOCK-COM (optional - defaults to current company)

This specifies the optional company id to which the resource lock is to apply.

When you initialized WW-LOCK-FIELDS this company field will be set to spaces which indicates the 'current' company id. This has been done as this is by far the most common requirement. However you can move in a specific company required.

Move LOW-VALUES to this company field to indicate that you require a system-wide resource lock.

WW-LOCK-TYP (mandatory)

This specifies a mandatory 10 character code to define the resource lock type.

This could be the name of the program or any other string that uniquely identifies the resource to be locked.

Note that as the field is 10 characters long you could use a combination of program or file name and a short string.

It is recommended that third party developers prefix their codes with a hyphen ('-') as none of the standard codes used by SYSPRO applications start with a hyphen.

WW-LOCK-KEY (mandatory)

This specifies a mandatory 80 character 'key' of the resource being locked.

In the example of the alternate stock code maintenance it would be logical to use the parent stock code being maintained as the key field.

If you have the situation where there is no 'key' then you can just move in the same code as moved to the field WW-LOCK-TYP. This field may not be left blank.

Output parameters

STAT-LCK

Logical value set if the resource is locked. See sample code below.

WW-LOCK-DES

The description of the resource lock.

WW-LOCK-OPR

The operator code showing who acquired the lock.

WW-LOCK-NAM

The operator name showing who acquired the lock.

WW-LOCK-DAT

The date that the lock was acquired in CCYYMMDD format.

WW-LOCK-TIM

The time that the lock was acquired in HHMMSSFF format (where FF means 1/100ths of a second).

WW-LOCK-REF

The optional reference against the resource lock.

WW-LOCK-FLG

The optional flag against the resource lock.

Remarks

You can use this function to test whether a resource lock has been acquired by another user.

When you wish to test for a resource lock you must initialize the group field named WW-LOCK-FIELDS and then populate the input fields as applicable.

Note that in most cases this just requires the type and key fields to be setup.

When you use the RESOURCE-LOCK-TEST-MSG function to test for a resource lock it can return a STAT-LCK status indicating that the resource is already locked by someone else. In this case a task dialog is displayed and the output fields are returned.

Note that there is an equivalent function called RESOURCE-LOCK-TEST that also returns the same fields and flags as this function except that it does NOT display any task dialog. You can use this to handle the fact that a resource is locked by someone else yourself.

Important - when you have finished with the resource it is best practice to remove the lock using RESOURCE-LOCK-DELETE.

Sample code

* Test for an 'alternate stock code' lock

* If locked then return a flag

INITIALIZE WW-LOCK-FIELDS.

MOVE D-COMPID TO WW-LOCK-COM.

MOVE "INVPAL" TO WW-LOCK-TYP.

MOVE D-ENT-STOCK TO WW-LOCK-KEY.

PERFORM RESOURCE-LOCK-TEST-MSG.

IF STAT-LCK

MOVE "L" TO D-LOCK-FLAG

ELSE

MOVE "Y" TO D-LOCK-FLAG

END-IF.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: standard

See also

Resource Locking, RESOURCE-LOCK-TEST, RESOURCE-LOCK-DELETE


RETRIEVE-PRINT-BY-FUNCTION

The RETRIEVE-PRINT-BY-FUNCTION function is used to restore the saved printer settings against a specific program function for the current operator. These are saved using the SET-PRINT-BY-FUNCTION function.

For example you can allow the current printer settings to be stored against an invoice. Later you can restore these settings before you print the invoice.

Input parameters

LINK-PRINT-FUNCT

This is a 6 character field that defines the document to be used. It is recommended that codes beginning with USR are used by third parties to avoid possible conflict with standard codes.

Output parameters

none

Remarks

This function restores the current printer settings for the function/current operator before the PRINT-OPEN function is performed. Note that the PRINT-CLOSE function resets the values back to the system default settings.

The SET-PRINT-BY-FUNCTION is used to store these settings.

You can use the CLR-PRINT-BY-FUNCTION to remove the saved settings for the function/operator code and GET-PRINT-BY-FUNCTION to check if printer settings have been saved.

The printer settings are stored in two C-ISAM files called ADMPRF.DAT and ADMPRH.DAT.

Sample code

*

** Save the current printer settings against document 'USRINV'

SAVE-USRINV.

MOVE "USRINV" TO LINK-PRINT-FUNCT.

PERFORM SET-PRINT-BY-FUNCTION.

*

** Restore printer settings for document 'USRINV'

RESTORE-USRINV.

MOVE "USRINV" TO LINK-PRINT-FUNCT.

PERFORM RETRIEVE-PRINT-BY-FUNCTION.

*

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE-NO-PRINT. *> Abort without printing

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

PRINT-OPEN, PRINT-CLOSE, SET-PRINT-BY-FUNCTION, CLR-PRINT-BY-FUNCTION, GET-PRINT-BY-FUNCTION


ROLLBACK-TRANSACTION

The ROLLBACK-TRANSACTION function is used to indicate that a logical business transaction that was started using the BEGIN-TRANSACTION function has failed.

This function is called internally by the COMER function whenever a transaction is in progress and should not normally be directly called by an application program.

See the description against the Transaction Processing topic and BEGIN-TRANSACTION function for additional details.

Input parameters

none

Output parameters

LINK-SQL-TRANSACT

This is an indicator showing whether a transaction is in progress. You can read this value but you must not change it. This function always sets it to spaces.

Y - Yes

Remarks

Transaction Processing is a concept that ensures that all data added, changed or deleted as part of a logical process is either completed successfully or completely undone – as if it had never happened.

See the description against BEGIN-TRANSACTION for more details.

Note that on a C-ISAM base company this will release all record lock held by the program.

When the ROLLBACK-TRANSACTION function is performed the Job Logging will be updated to show that a rollback was issued on a SQL Server based company and that the transaction failed on a C-ISAM company.

Sample code

* Start a transaction

MOVE "Debit A $100 and Credit B $100" TO LINK-SQL-TRAN-TEXT.

MOVE "E" TO COMER-TO-ENDJOB.

PERFORM BEGIN-TRANSACTION.

* Credit A with $100

MOVE COMPID TO GENMST-CMP.

MOVE "A" TO GENMST-ACC.

PERFORM GENMST-READ.

PERFORM COMER.

ADD 100 TO GENMST-DR. *> Add to Period to date Debits $100

ADD 100 TO GENMST-CBAL. *> Update balance

PERFORM GENMST-REWRITE.

PERFORM COMER

* Credit B with $100

MOVE COMPID TO GENMST-CMP.

MOVE "B" TO GENMST-ACC.

PERFORM GENMST-READ.

PERFORM COMER.

ADD 100 TO GENMST-CR. *> Add to Prd to date Credits

SUBTRACT 100 FROM GENMST-CBAL. *> Update balance

PERFORM GENMST-REWRITE.

PERFORM COMER

* Done

PERFORM COMMIT-TRANSACTION.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Transaction Processing, BEGIN-TRANSACTION, COMMIT-TRANSACTION, ROLLBACK-TRANSACTION, COMER


SERV

The SERV function is used by a potentially long running program to provide the user with an indicator of it's progress and allow the operator to interrupt and optionally cancel the process. This is most commonly used by report programs. This function requires some equivalent dialog defined in the screenset.

There is a tickover setting defined against each operator that allows a system administrator to define the frequency of these refreshes. Calling the screenset too often in a client/server environment can have a serious effect on the performance of the system.

Input parameters

D-TICKOVER

Typically the screenset will have a datablock field defined that is used to show the operator the current status of the process. This is often called D-TICKOVER but can be any name required. The program will often move in the primary key of the file being processed (such as the customer number when processing the A/R master file) to give the operator an idea of the progress.

Output parameters

ANS

This is an indicator showing whether the operator attempted to interrupt the processing of the program.

Y - Yes

Remarks

It is highly recommended that potentially long running tasks keep the operator informed of their progress. If a program does not keep the operator informed then they may think that the process has failed or hung and attempt to kill it using the Windows task manager.

Some long running tasks must not be cancelled, in this case use the TICKOVER function to keep the operator informed of the process status. However if the process is simply reading data often the operator can interrupt and optionally end the report prematurely. This is the purpose of the SERV function.

Note that for this function to work correctly the screenset requires some dialog to interact with the user appropriately. See the SDK sample program SDKP25 for an example of the dialog required.

Note that in a client/server environment excessive network traffic (between the server and the client) can cause serious degradation to the performance of the process. To assist in system tuning there is a tickover setting defined against each operator that allows a system administrator to define the frequency of these refreshes.

By rows

When defining the tickover by number of rows this indicates that for every x times that the SERV function is called the screenset will be called once. For example if defined every 10 rows then every tenth time SERV is called the screenset will be called.

By time

When defining the tickover setting by time this indicates that the screenset will only be called when the time has elapsed since the last time the screenset was called. For example if the tickover is defined for 5 seconds then the SERV function will not call the screenset more often than every 5 seconds. Note that depending on the number of times that SERV is called the program may well take longer than 5 seconds between calling the screenset.

If the program needs to guarantee that the screenset is called (ie the settings defined against the operator are temporarily superseded for the next call only) then before the SERV function is used the function RESET-TICKOVER should be called. This is useful when changing a phase message or another change to the text on the screen is required.

If the operator has clicked on the Cancel push button the SERV function will return a Y in the field ANS. This typically causes a standard 'You have interrupted processing' message to be shown allowing the operator to Resume or End. If End is selected then the program will branch to the CANCELREQ paragraph that must be defined against every SYSPRO program. This typically prints the message Report Cancelled.

Sample code

MOVE ARSMST-CUS TO D-TICKOVER. *> Show the current customer

PERFORM SERV.

IF ANS = "Y"

PERFORM SERVREQ.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

SERVREQ, TICKOVER, RESET-TICKOVER


SERVREQ

The SERVREQ function is used by a program when the operator has interrupted a process, often a report. A standard dialog box will be shown allowing the operator to Resume or End the process.

This is typically used together with the SERV function.

Input parameters

SERVREQ-TO-CANCELREQ

This indicator defines whether the program should branch to CANCELREQ if the operator clicks End. This is the default setting.

N – Do not branch to CANCELREQ if End selected. In this case the field ANS should be used to determine whether the operator clicked on End.

Output parameters

ANS

This is an indicator showing whether the operator wants to cancel the process.

N – Operator wants to cancel the process

Remarks

When this function is called a standard dialog box is displayed allowing the operator to Resume or End the process.

By default when an operator Ends the process the program will branch to CANCELREQ which must be defined against every SYSPRO program. Typically a report will print the Report Cancelled message to clearly show that the report was terminated prematurely.

However if required you can control the program flow by moving N to the field SERVREQ-TO-CANCELREQ.

See the notes against SERV for more details about tickovers, long running processes and configuring the operator settings.

Sample code

MOVE ARSMST-CUS TO D-TICKOVER. *> Show the current customer

PERFORM SERV.

IF ANS = "Y"

PERFORM SERVREQ.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

SERV, TICKOVER, RESET-TICKOVER


SET-DIRECTORY-ON-CLIENT

The SET-DIRECTORY-ON-CLIENT function is used to change the current directory on the client PC.

In a Client/Server environment this will be issued on the Client PC. This will always be a Windows environment.

Important - You must remember to restore the original directory before SYSPRO continues.

Input parameters

LINK-EXTRA-1

This is the required directory on the Client PC. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to change to the required directory.

Zero - Yes

Remarks

If the required directory is spacey then it must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

In a client/server system the command is executed on the client PC.

In a mapped drive system the command is executed on the client PC.

Remember to use GET-DIRECTORY-ON-CLIENT to store the existing directory before changing the directory. This can then be restored when required.

Sample code

* Retrieve the current directory

PERFORM GET-DIRECTORY-ON-CLIENT.

MOVE LINK-EXTRA-1 TO D-CURRENT-DIRECTORY.

* Now change the current directory

MOVE "C:\TEMP" TO LINK-EXTRA-1.

PERFORM SET-DIRECTORY-ON-CLIENT.

IF LINK-IMPWSH-STA = ZERO

PERFORM FUNCTION-IN-NEW-DIRECTORY.

* Restore original directory

MOVE D-CURRENT-DIRECTORY TO LINK-EXTRA-1.

PERFORM SET-DIRECTORY-ON-CLIENT.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file names, GET-DIRECTORY-ON-SERVER, GET-DIRECTORY-ON-CLIENT, SET-DIRECTORY-ON-SERVER, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSSETD


SET-FORCE-CHANGE-PASSWORD

The SET-FORCE-CHANGE-PASSWORD function is used to force an operator to change their operator password the next time they login.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being set.

You must enter 'ADMOPR' to specify operator passwords.

LINK-PASS-CMP

This is the company id of the key required.

You must enter spaces to specify operator passwords.

LINK-PASS-KEY

This is the key of the item being protected.

You must enter the operator code.

Output parameters

None

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The SET-FORCE-CHANGE-PASSWORD function is used to force an operator to set a new password the next time they login. It must only be used for operator passwords and no other password type.

There is a CLEAR-FORCE-CHANGE-PASSWORD function that clears the 'force password change' flag.

Sample code

* Force operator 'NEW' to change their password

MOVE SPACES TO LINK-PASS.

MOVE "NEW" TO LINK-PASS-KEY. *> Operator code

PERFORM SET-FORCE-CHANGE-PASSWORD.

Requirements

Version: Included in SYSPRO 6.1 port 29 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD, CLEAR-FORCE-CHANGE-PASSWORD


SET-DIRECTORY-ON-SERVER

The SET-DIRECTORY-ON-SERVER function is used to change the current directory on the server.

In a Client/Server environment this will be issued on the server. This may be a Windows or Unix system.

Important - You must remember to restore the original directory before SYSPRO continues.

Input parameters

LINK-EXTRA-1

This is the required directory on the server. It must be quoted if spacey.

Output parameters

LINK-IMPWSH-STA

This flag indicates whether the system was able to change to the required directory.

Zero - Yes

Remarks

If the required directory is spacey then it must be surrounded with quotes. See the QUOTE-VALID-FILE-NAME and STRIP-VALID-FILE-NAME functions.

In a client/server system the command is executed on the server.

In a mapped drive system the command is executed on the client PC.

Remember to use GET-DIRECTORY-ON-SERVER to store the existing directory before changing the directory. This can then be restored when required.

Sample code

* Retrieve the current directory

PERFORM GET-DIRECTORY-ON-SERVER.

MOVE LINK-EXTRA-1 TO D-CURRENT-DIRECTORY.

* Now change the current directory

IF LINK-OS = "U"

MOVE "/tmp" TO LINK-EXTRA-1

ELSE

MOVE "C:\TEMP" TO LINK-EXTRA-1.

PERFORM SET-DIRECTORY-ON-SERVER.

IF LINK-IMPWSH-STA = ZERO

PERFORM FUNCTION-IN-NEW-DIRECTORY.

* Restore original directory

MOVE D-CURRENT-DIRECTORY TO LINK-EXTRA-1.

PERFORM SET-DIRECTORY-ON-SERVER.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

spacey file names, GET-DIRECTORY-ON-SERVER, GET-DIRECTORY-ON-CLIENT, SET-DIRECTORY-ON-CLIENT, QUOTE-VALID-FILE-NAME, STRIP-VALID-FILE-NAME, S-OSSETDS


SET-PASSWORD

The SET-PASSWORD function is used to allow a new password to be defined. If there is an existing password this will need to be entered before a new one can be set.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being set.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

LINK-PASS-KEY

This is the key of the item being protected.

For example when setting the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

Output parameters

LINK-PASS-OK

This flag indicates whether the operator set a new password.

Spaces – Yes

N – Password was not set

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The SET-PASSWORD function allows a new password to be defined. If any existing password exists then it must be entered before a new password can be set. The system will return a flag indicating whether a new password was set successfully.

Note that for operator passwords it is possible to configure various rules that must be satisfied before a new password is accepted.

Sample code

* Set the password to change a S/Order line price

MOVE SPACES TO LINK-PASS.

MOVE "-SOR03" TO LINK-PASS-TYP. *> See IMPPSS.IMP for codes

PERFORM SET-PASSWORD.

IF LINK-PASS-OK = SPACES

MOVE SPACES TO LINK-EXTRA

GO TO NEW-PASSWORD-SET

ELSE

MOVE SPACES TO LINK-EXTRA

GO TO OLD-PASSWORD-IN-FORCE.

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD-NO-OLD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD


SET-PASSWORD-NO-ASK

The SET-PASSWORD-NO-ASK function is used to allow a new password to be defined. It assumes that your application has already asked for the new password – preferably reconfirming it. This function is then used to set the password without asking anything else.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being set.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

LINK-PASS-KEY

This is the key of the item being protected.

For example when setting the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

LINK-PASS-ENT

This is the unencrypted version of the password that the user has entered in your application. It can be up to 30 characters long.

Output parameters

none

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The SET-PASSWORD-NO-ASK function allows your application to request a new password and have the SYSPRO password system store it. Note that if there is any existing password then it will be silently overwritten. If you wish you can use the VERIFY-PASSWORD function to check any previous password.

It is recommended that whenever you request a new password that the operator is asked to confirm the password to help prevent a typing mistake.

Sample code

* Set the password to change a S/Order line price

MOVE SPACES TO LINK-PASS.

MOVE "-SOR03" TO LINK-PASS-TYP. *> See IMPPSS.IMP for codes

MOVE D-NEW-PASS TO LINK-PASS-ENT.

PERFORM SET-PASSWORD-NO-ASK.

MOVE SPACES TO LINK-PASS.

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-OLD, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD


SET-PASSWORD-NO-OLD

The SET-PASSWORD-NO-OLD function is used to allow a new password to be defined. If there is an existing password this will not be requested before a new one can be set.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being set.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

LINK-PASS-KEY

This is the key of the item being protected.

For example when setting the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

Output parameters

LINK-PASS-OK

This flag indicates whether the operator set a new password.

Spaces – Yes

N – Password was not set

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The SET-PASSWORD-NO-OLD function allows a new password to be defined without prompting for any existing password. It is recommended that only system administrators be able to use this function.

Sample code

* Set the password to change a S/Order line price

MOVE SPACES TO LINK-PASS.

MOVE "-SOR03" TO LINK-PASS-TYP. *> See IMPPSS.IMP for codes

PERFORM SET-PASSWORD-NO-OLD.

IF LINK-PASS-OK = SPACES

MOVE SPACES TO LINK-PASS

GO TO NEW-PASSWORD-SET

ELSE

MOVE SPACES TO LINK-PASS

GO TO OLD-PASSWORD-IN-FORCE.

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, VERIFY-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD


SET-PRINT-BY-FUNCTION

The SET-PRINT-BY-FUNCTION function is used to store the current printer settings against a specific program function for the current operator. You can later restore these printer settings when printing the document.

For example you can allow the current printer settings to be stored against an invoice. Later you can restore these settings before you print the invoice.

This is part of the Printer per function facility.

Input parameters

LINK-PRINT-FUNCT

This is a 6 character field that defines the document to be used. It is recommended that codes beginning with USR are used by third parties to avoid possible conflict with standard codes.

Output parameters

none

Remarks

This function saves the current printer settings for the function/current operator.

The RETRIEVE-PRINT-BY-FUNCTION is later used to restore these settings before using the PRINT-OPEN function.

You can use the CLR-PRINT-BY-FUNCTION to remove the saved settings for the function/operator code and GET-PRINT-BY-FUNCTION to determine whether there is any saved printer settings.

The printer settings are stored in two C-ISAM files called ADMPRF.DAT and ADMPRH.DAT.

Sample code

*

** Save the current printer settings against document 'USRINV'

SAVE-USRINV.

MOVE "USRINV" TO LINK-PRINT-FUNCT.

PERFORM SET-PRINT-BY-FUNCTION.

*

** Restore printer settings for document 'USRINV'

RESTORE-USRINV.

MOVE "USRINV" TO LINK-PRINT-FUNCT.

PERFORM RETRIEVE-PRINT-BY-FUNCTION.

*

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

MOVE "Second line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE-NO-PRINT. *> Abort without printing

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

Printer per function, PRINT-OPEN, PRINT-CLOSE, RETRIEVE-PRINT-BY-FUNCTION, CLR-PRINT-BY-FUNCTION, GET-PRINT-BY-FUNCTION


STRIP-VALID-FILE-NAME

The STRIP-VALID-FILE-NAME function is used to ensure that there is no quotes around a file name. This function should be used before using a Win32 API call or storing a file name into an XML document.

Generally Net Express programs require a spacey file name to be quoted.

Input parameters

WW-FILE-NAME

The file name to have quotes removed.

Output parameters

WW-FILE-NAME

File name without quotes.

Remarks

Win32 API calls and other non-Net Express systems must not have quotes included in a file name. This function should be used before calling these systems to ensure that spacey file name will work correctly.

Programs often use QUOTE-VALID-FILE-NAME to add quotes when required.

Sample code

MOVE '"C:\Documents and Settings\File.txt"' TO WW-FILE-NAME.

PERFORM STRIP-VALID-FILE-NAME.

MOVE WW-FILE-NAME TO WIN32-FILE-NAME.

This results in C:\Documents and Settings\File.txt in WW-FILE-NAME.

Requirements

Version: Included in Encore 5.0 issue 007 and Encore 5.1 issue 003 and later

Copybooks: Standard

See also

spacey file name. QUOTE-VALID-FILE-NAME


SQL-GENERATE-WHERE-LIKE

The SQL-GENERATE-WHERE-LIKE function can be used when building SQL statements when a LIKE phrase is to be used.

See the topic SQL Server Tuning for an overview of SQL performance issues.

Input parameters

WW-LINK-1

The string to be expanded for use in a LIKE phrase. Can contain wildcards '*' and '?'.

Output parameters

WW-LINK-1

The expanded string that can be used in a LIKE phrase.

Remarks

When using SQL Server Tuning you may require to use a WHERE clause with a LIKE phrase. This is useful when searching for items that match a pattern (wildcard) as opposed to an exact match. However the syntax for pattern matching is different from the normal wildcards as shows below:

Regular wildcard | SQL LIKE wildcard | Description
* (asterisk) | % (percent) | Matches zero or more characters
? (question mark) | _ (underscore) | Matches any single character

In addition, by default, SYSPRO is best installed on a case sensitive database and usually any pattern matching must ignore the case. This is done by defining that each alphabetic character can be either upper or lower case - performed by specifying each character using a square bracket and both upper and lower case values. For example searching for the letter 'a' in any case requires the string '[Aa]'.

Suppose that you are searching SYSPRO contacts for people with the name 'John' anywhere in their full name then the SQL WHERE clause would be.

SELECT a.FullName

FROM CrmContact a

WHERE a.FullName LIKE '%[Jj][Oo][Hh][Nn]%'

Using this function you can pass the regular wildcard '*John*' (any case) and it will be expanded to '%[Jj][Oo][Hh][Nn]%'.

Sample code

* Assume 'John'

MOVE "John" TO REGULAR-SEARCH-STRING.

MOVE SPACES TO WW-LINK-1.

STRING

"*" DELIMITED BY SIZE

REGULAR-SEARCH-STRING DELIMITED BY " "

"*" DELIMITED BY SIZE

INTO WW-LINK-1.

PERFORM SQL-GENERATE-WHERE-LIKE.

MOVE WW-LINK-1 TO SQL-SEARCH-STRING.

* You can now move 'SQL-SEARCH-STRING' to the field

* SQL-CON when issuing an optimized SQL command

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: Standard

See also

SQL Server Tuning


SQL-RESET-FAST-CURSOR

The SQL-RESET-FAST-CURSOR function can be used to improve performance on a SQL Server based system.

This function together with the SQL-SET-FAST-CURSOR can be used to optimize SQL performance. See the Remarks section for important information.

See the topic SQL Server Tuning for an overview of SQL performance issues.

Input parameters

none

Output parameters

none

Remarks

When using the generic file handlers in a SQL Server environment occasionally you may need to read many records sequentially using PERFORM XXXXXX-READ-NEXT - where XXXXXX is the file code.

In this case you can use the SQL-SET-FAST-CURSOR and SQL-RESET-FAST-CURSOR functions to temporarily enable a very fast cursor access.

It is very important that from the time you issue the SQL-SET-FAST-CURSOR function until you issue the SQL-RESET-FAST-CURSOR function that the only SQL file handling is the PERFORM XXXXXX-READ-NEXT function on a single file.

By 'bracketing' a large number of consecutive READ-NEXT statements you can gain considerably performance benefits - up to 6 times faster is common.

The program that transfers data from ISAM to SQL (IMPSQM) uses this functionality to gain about a 6 times speed improvement.

Sample code

PERFORM SQL-SET-FAST-CURSOR.

MOVE 1 TO XX1.

PERFORM READ-STOCK-CODES 1000 TIMES.

PERFORM SQL-RESET-FAST-CURSOR.

READ-STOCK-CODES

PERFORM INVMST-READ-NEXT.

MOVE INVMST-STK TO STOCK-CODE(XX1).

ADD 1 TO XX1

Requirements

Version: Included in Encore 6.0 issue 006

Copybooks: Standard

See also

SQL Server Tuning, SQL-SET-FAST-CURSOR


SQL-SET-FAST-CURSOR

The SQL-SET-FAST-CURSOR function can be used to improve performance on a SQL Server based system.

This function together with the SQL-RESET-FAST-CURSOR can be used to optimize SQL performance. See the Remarks section for important information.

See the topic SQL Server Tuning for an overview of SQL performance issues.

Input parameters

none

Output parameters

none

Remarks

When using the generic file handlers in a SQL Server environment occasionally you may need to read many records sequentially using PERFORM XXXXXX-READ-NEXT - where XXXXXX is the file code.

In this case you can use the SQL-SET-FAST-CURSOR and SQL-RESET-FAST-CURSOR functions to temporarily enable a very fast cursor access.

It is very important that from the time you issue the SQL-SET-FAST-CURSOR function until you issue the SQL-RESET-FAST-CURSOR function that the only SQL file handling is the PERFORM XXXXXX-READ-NEXT function on a single file.

By 'bracketing' a large number of consecutive READ-NEXT statements you can gain considerably performance benefits - up to 6 times faster is common.

The program that transfers data from ISAM to SQL (IMPSQM) uses this functionality to gain about a 6 times speed improvement.

Sample code

PERFORM SQL-SET-FAST-CURSOR.

MOVE 1 TO XX1.

PERFORM READ-STOCK-CODES 1000 TIMES.

PERFORM SQL-RESET-FAST-CURSOR.

READ-STOCK-CODES

PERFORM INVMST-READ-NEXT.

MOVE INVMST-STK TO STOCK-CODE(XX1).

ADD 1 TO XX1

Requirements

Version: Included in Encore 6.0 issue 006

Copybooks: Standard

See also

SQL Server Tuning, SQL-RESET-FAST-CURSOR


TEXT-TO-HTML

The TEXT-TO-HTML function is used to translate plain text to text that can be used in an XML or HTML element value. This typically requires the characters <, > and & to be translated to their character entity values.

Input parameters

WW-LINK-1

The plain text to be translated.

Output parameters

WW-LINK-1

The text that can be placed into an XML or HTML element value.

Remarks

This function is used to translate plain text to text that can be used in an XML or HTML element value. This typically requires the characters <, > and & to be translated to their character entity values.

The character entities supported are:

Character | Character entity
< | &lt;
> | &gt;
& | &amp;

Sample code

MOVE "This is text with < and > and &." TO WW-LINK-1.

PERFORM TEXT-TO-HTML.

MOVE WW-LINK-1 TO VALID-XML-ELEMENT-VALUE.

Requirements

Version: Included in Encore 6.0 issue 007

Copybooks: Standard

See also

Well Formed XML, HTML-TO-TEXT


TICKOVER

The TICKOVER function is used by a program that performs a potentially long-running task to indicate to the end-user the status of the process. Often this is the key of the item being processed. To use this function successfully requires dialog in the screenset.

Input parameters

None required but usually a data block field D-TICKOVER is used

Output parameters

none

Remarks

It is recommended that a datablock field called D-TICKOVER is used to pass the item being processed. For example a program processing the Inventory master table will usually display the stock code.

The TICKOVER function uses the option defined against the operator to determine how often the screenset is actually called. This can be defined by a number of rows or by a time. By reducing the network traffic – especially on a client/server system – the performance of the system can be considerably improved.

When defining the tickover option by rows against the operator this means that for every x times the TICKOVER function is called the screenset will be called once. For example if set to 10 rows then every tenth time the TICKOVER function is called the screenset will be called.

When defining the tickover option by time this indicates that it doesn't matter how quickly the TICKOVER function is called the screenset will not be called more often than the time shown. For example if 2 seconds is defined then the TICKOVER function will never call the screenset more often than once every two seconds. Note that the screenset may be called less frequently depending on how often the TICKOVER function is called by the program.

If a program needs to force the TICKOVER function to call the screenset regardless of the operator settings (for example when changing a phase of processing) the function RESET-TICKOVER should be used before using the TICKOVER function. This forces the next TICKOVER to call the screenset.

See your operator setup to determine what TICKOVER options are available.

Sample code

MOVE INVMST-STK TO D-TICKOVER.

PERFORM TICKOVER.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

RESET-TICKOVER, SERV


TRANSLATE-TEXT

The TRANSLATE-TEXT function is used to translate English text into another language or to apply any language customization that has been configured at the site.

Input parameters

LINK-EXTRA

The English phrase to be translated.

Output parameters

LINK-EXTRA

The translated text to be used.

Remarks

Important - This function adds an overhead, over-and-above the regular SYSPRO language translation capabilities, and should be used with caution. Regular user interface elements, such as window titles, plain text, pane titles, listview column headings, display and entry form captions, toolbar and ToolTip text etc, are all handled by the standard SYSPRO architecture. Using the TRANSLATE-TEXT function in a client-server environment causes a round trip to the client and back again.

Regular SYSPRO language translation capabilities are client-based. When you login to SYSPRO a dictionary (or multiple dictionaries) are loaded into memory and each relevant user interface element is tested against the dictionary for a foreign language equivalent (or a customized phrase). The lookup value (if any) is used in place of the original text.

However there are some cases where it is more effective to lookup a phrase from your server-based code. These typically fall into two types:

1. General phrase lookup

Your program may wish to translate a phrase for later viewing or to be embedded within other text or maybe you wish a phrase to be inserted into a file (e.g. a plain text or XML file). In this case the TRANSLATE-TEXT function could be used.

2. Business object phrase lookup

When developing programs and functions that work in a COM environment (e.g. when running e.net Solutions or running a VBScript or from a query business object from SRS) these programs do not have access to any client-side technology. Therefore they require to use the TRANSLATE-TEXT function for any required translation.

For example when developing query business objects for use in a SYSPRO Reporting Services (SRS) environment.

Phrases with variable data

The TRANSLATE-TEXT function takes account of variables in exactly the same way as the regular SYSPRO language translation. For example phrases such as:

Stock code 'B100' not found

will be translated leaving the 'B100' parameter intact.

Similarly the phrase:

Company login: ADMIN - System Administrator

will translate the 'Company login' part of the phrase and leave the part after the colon+space as is.

Multiple phrases

If you wish to translate more than a single phrase from server-side code then consider using a set of functions that have been developed specifically for this purpose. These are more efficient that calling the TRANSLATE-TEXT function multiple times. See the function TRANSLATE-TEXT-INIT and related functions - TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-LIST and TRANSLATE-TEXT-GET.

Generating compound phrases

Note you should avoid building compound phrases by using multiple translated phrases as, depending on the language syntax, this may or may not make sense in the target language. See the Language Translation topic for more information about techniques available to a SYSPRO developer.

For example do not attempt to build a phrase such as 'Accounts Payable module not installed' by translating 'Accounts Payable' and 'module not found' and concatenating them together. In this example you could be better translating the phrase as a whole, or to reduce the number of phrases something like:

'The following module is not installed - Accounts Payable'

Sample code

MOVE "Stock code" TO LINK-EXTRA.

PERFORM TRANSLATE-TEXT.

MOVE LINK-EXTRA TO TRANSLATED-TEXT-MSG-1.

*

MOVE "Stock code 'B100' not found." TO LINK-EXTRA.

PERFORM TRANSLATE-TEXT.

MOVE LINK-EXTRA TO TRANSLATED-TEXT-MSG-2.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: Standard

See also

Language Translation, TRANSLATE-TEXT-INIT


TRANSLATE-TEXT-INIT

The TRANSLATE-TEXT-INIT function is used as the first in a set of functions to translate multiple English phrases into another language or to apply any language customization that has been configured at the site.

Input parameters

none

Output parameters

none

Remarks

Important - These function add an overhead, over-and-above the regular SYSPRO language translation capabilities, and should be used with caution. Regular user interface elements, such as window titles, plain text, pane titles, listview column headings, display and entry form captions, toolbar and ToolTip text etc, are all handled by the standard SYSPRO architecture. Using the TRANSLATE-TEXT-INIT and related functions in a client-server environment causes a round trip to the client and back again.

Regular SYSPRO language translation capabilities are client-based. When you login to SYSPRO a dictionary (or multiple dictionaries) are loaded into memory and each relevant user interface element is tested against the dictionary for a foreign language equivalent (or a customized phrase). The lookup value (if any) is used in place of the original text.

However there are some cases where it is more effective to lookup a phrase from your server-based code. These typically fall into two types:

1. General phrase lookup

Your program may wish to translate a phrase for later viewing or to be embedded within other text or maybe you wish a phrase to be inserted into a file (e.g. a plain text or XML file). In this case the TRANSLATE-TEXT-INIT set of functions could be used.

2. Business object phrase lookup

When developing programs and functions that work in a COM environment (e.g. when running e.net Solutions or running a VBScript or from a query business object from SRS) these programs do not have access to any client-side technology. Therefore they require to use the TRANSLATE-TEXT-INIT set of functions for any required translation.

For example when developing query business objects for use in a SYSPRO Reporting Services (SRS) environment.

Phrases with variable data

The TRANSLATE-TEXT-INIT set of functions takes account of variables in exactly the same way as the regular SYSPRO language translation. For example phrases such as:

Stock code 'B100' not found

will be translated leaving the 'B100' parameter intact.

Similarly the phrase:

Company login: ADMIN - System Administrator

will translate the 'Company login' part of the phrase and leave the part after the colon+space as is.

Single phrase

If you wish to translate a single phrase from server-side code then you should rather use the TRANSLATE-TEXT function.

Generating compound phrases

Note you should avoid building compound phrases by using multiple translated phrases as, depending on the language syntax, this may or may not make sense in the target language. See the Language Translation topic for more information about techniques available to a SYSPRO developer.

For example do not attempt to build a phrase such as 'Accounts Payable module not installed' by translating 'Accounts Payable' and 'module not found' and concatenating them together. In this example you could be better translating the phrase as a whole, or to reduce the number of phrases something like:

'The following module is not installed - Accounts Payable'

How to use the set of functions to translate multiple phrases

To initialize the multiple phrase translation logic you must first use PERFROM TRANSLATE-TEXT-INIT.

Then for each phrase to be translated move a single phrase to LINK-EXTRA and PERFORM TRANSLATE-TEXT-ADD. This adds each phrase to a list.

Once all phrases to be translated have been added to the list then use PERFORM TRANSLATE-TEXT-LIST. This performs the translations and in a client-server environment passes the list to and from the client.

Lastly for each phrase translated use PERFORM TRANSLATE-TEXT-GET to retrieve the phrases (in the sequence that they were added) into LINK-EXTRA.

Once you have retrieved the same number of phrases as you originally added to the list any resources consumed by the process will be returned back to the system.

See the following example code.

Sample code

01 MSG-001 PIC X(30) VALUE "Stock code".

01 MSG-002 PIC X(100) VALUE "Stock code 'B100' not found".

01 MSG-003 PIC X(100) VALUE "Company login: ADMIN - System Administrator".

*

** Initialize phrase list

PERFORM TRANSLATE-TEXT-INIT.

*

** Add each phrase to list

MOVE MSG-001 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-002 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-003 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

*

** Translate all phrases in the list

PERFORM TRANSLATE-TEXT-LIST.

*

** Fetch each phrase from the translated list

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-001.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-002.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-003.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: Standard

See also

Language Translation, TRANSLATE-TEXT, TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-GET, TRANSLATE-TEXT-LIST


TRANSLATE-TEXT-ADD

The TRANSLATE-TEXT-ADD function is used as part of a set of functions to translate multiple English phrases into another language or to apply any language customization that has been configured at the site.

See the remarks against the TRANSLATE-TEXT-INIT function for a complete description about how to use this set of language translate functions.

Input parameters

LINK-EXTRA

English phrase to be translated

Output parameters

OPERATOR-TRAN-COUNT

Number of phrases added to the list (one upwards).

Remarks

The TRANSLATE-TEXT-ADD function accepts an English phrase in LINK-EXTRA and adds it to the list of phrases to be translated. The field OPERATOR-TRAN-COUNT will contain the number of phrases added to the list of phrases using this function.

You must have first performed the TRANSLATE-TEXT-INIT function before using this function.

See the following example code.

Sample code

01 MSG-001 PIC X(30) VALUE "Stock code".

01 MSG-002 PIC X(100) VALUE "Stock code 'B100' not found".

01 MSG-003 PIC X(100) VALUE "Company login: ADMIN - System Administrator".

*

** Initialize phrase list

PERFORM TRANSLATE-TEXT-INIT.

*

** Add each phrase to list

MOVE MSG-001 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-002 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-003 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

*

** Translate all phrases in the list

PERFORM TRANSLATE-TEXT-LIST.

*

** Fetch each phrase from the translated list

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-001.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-002.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-003.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: Standard

See also

Language Translation, TRANSLATE-TEXT, TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-GET, TRANSLATE-TEXT-LIST


TRANSLATE-TEXT-GET

The TRANSLATE-TEXT-GET function is used as part of a set of functions to translate multiple English phrases into another language or to apply any language customization that has been configured at the site.

See the remarks against the TRANSLATE-TEXT-INIT function for a complete description about how to use this set of language translate functions.

Input parameters

OPERATOR-TRAN-COUNT

The phrase number from the original list. It is recommended that you do not change this value.

Output parameters

LINK-EXTRA

Foreign language or customized phrase

OPERATOR-TRAN-COUNT

This field will be incremented from the original input value.

Zero means that the last phrase has been returned.

STAT-AT-END

You have attempted to read more phrases that the original list provided - the field LINK-EXTRA is invalid.

Remarks

The TRANSLATE-TEXT-GET function retrieves the next translated phrase from the original list of phrases.

You must have first performed the TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-ADD and TRANSLATE-TEXT-LIST functions before using this function.

The input field OPERATOR-TRAN-COUNT defines the phrase number from the original list. After performing the TRANSLATE-TEXT-LIST function this value is set to 1 so that the next TRANSLATE-TEXT-GET function retrieves the first phrase. The OPERATOR-TRAN-COUNT field is incremented after each TRANSLATE-TEXT-GET function so that the next phrase is retrieved each time.

After the final phrase is retrieved the field OPERATOR-TRAN-COUNT will be set to zero.

In addition the STAT-AT-END logical value will be set to True when you have attempted to retrieve a phrase beyond the number originally added.

See the following example code.

Sample code

01 MSG-001 PIC X(30) VALUE "Stock code".

01 MSG-002 PIC X(100) VALUE "Stock code 'B100' not found".

01 MSG-003 PIC X(100) VALUE "Company login: ADMIN - System Administrator".

*

** Initialize phrase list

PERFORM TRANSLATE-TEXT-INIT.

*

** Add each phrase to list

MOVE MSG-001 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-002 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-003 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

*

** Translate all phrases in the list

PERFORM TRANSLATE-TEXT-LIST.

*

** Fetch each phrase from the translated list

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-001.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-002.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-003.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: Standard

See also

Language Translation, TRANSLATE-TEXT, TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-LIST


TRANSLATE-TEXT-LIST

The TRANSLATE-TEXT-LIST function is used as part of a set of functions to translate multiple English phrases into another language or to apply any language customization that has been configured at the site.

See the remarks against the TRANSLATE-TEXT-INIT function for a complete description about how to use this set of language translate functions.

Input parameters

none

Output parameters

OPERATOR-TRAN-COUNT

Set to 1 - do not change this value.

Remarks

The TRANSLATE-TEXT-LIST function performs the actual language translation of a set of phrases accumulated using the TRANSLATE-TEXT-ADD function. The field OPERATOR-TRAN-COUNT is set to 1 so that the next OPERATOR-TRAN-GET function returns the first phrase from the list. It is recommended that you do not change this value.

You must have first performed the TRANSLATE-TEXT-INIT and TRANSLATE-TEXT-ADD functions before using this function.

See the following example code.

Sample code

01 MSG-001 PIC X(30) VALUE "Stock code".

01 MSG-002 PIC X(100) VALUE "Stock code 'B100' not found".

01 MSG-003 PIC X(100) VALUE "Company login: ADMIN - System Administrator".

*

** Initialize phrase list

PERFORM TRANSLATE-TEXT-INIT.

*

** Add each phrase to list

MOVE MSG-001 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-002 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

MOVE MSG-003 TO LINK-EXTRA.

PERFORM TRANSLATE-LIST-ADD.

*

** Translate all phrases in the list

PERFORM TRANSLATE-TEXT-LIST.

*

** Fetch each phrase from the translated list

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-001.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-002.

PERFORM TRANSLATE-TEXT-GET.

MOVE LINK-EXTRA TO MSG-003.

Requirements

Version: Included in SYSPRO 6.1 and later.

Copybooks: Standard

See also

Language Translation, TRANSLATE-TEXT, TRANSLATE-TEXT-ADD, TRANSLATE-TEXT-INIT, TRANSLATE-TEXT-LIST


UNPACK-CASES-AND-PIECES

The UNPACK-CASES-AND-PIECES function is used to unpack an alphanumeric string potentially with cases and pieces separated by a slash (/) into two separate numeric values. The Cases and Pieces function is alternatively known as Unit Quantity.

Input parameters

NUMB-R

An alphanumeric string optionally containing cases and pieces separated by a forward slash.

Output parameters

NUM

The number of cases. This is the value before any slash (/) character.

NUM-VAL

The number of pieces. This is the value after any slash (/) character.

NUM-OK

A flag indicating that the input field contains valid numeric editing characters. These include the digits 0-9 a minus sign (-) and a slash character (/) all other characters (excluding spaces) are invalid including thousands separators.

Remarks

This function is used by programs where a stock code is defined as having Unit Quantity Processing. It takes a string and unpacks this into two numeric fields.

Note that both NUM and NUM-VAL will always have the same sign.

If the operator has entered 100/15 then the values will be returned as:

NUM 100

NUM-VAL 15

If the operator has entered 100/15- then the values will be returned as:

NUM 100-

NUM-VAL 15-

Sample code

MOVE D-ASK-CASES-AND-PIECES TO NUMB-R.

PERFORM UNPACK-CASES-AND-PIECES.

IF NUM-OK = "Y"

MOVE NUM TO NUMBER-OF-CASES

MOVE NUM-VAL TO NUMBER-OF-PIECES

ELSE

GO TO INVALID-CASES-AND-PIECES.

Requirements

Version: Included in Encore 5.1 and later

Copybooks: standard

See also

NUMB-CHECK


UNPACK-INPUT-BYTE

The UNPACK-INPUT-BYTE function is used to unpack a single 8 bit byte into it's individual bits. It is then simple to check whether one or more of the bits are set or unset.

This is typically used when using a Win32 API call or calling a third party system. Generally SYSPRO programs do not set/clear single bits when returning information.

Input parameters

INPUT-BYTE-COMPX

This single 8-bit byte numeric field contains the value to be tested.

INPUT-BYTE

This is a single alphanumeric character that is redefined by INPUT-BYTE-COMPX and can be used where a string is to be tested.

Output parameters

BIT-X(nn)

This is an array of 8 numeric fields with a value or zero or one.

Subscript 1 represents the most significant bit

BIT-1

This is a single numeric field indicating the value of bit 1 (where bit 1 is the least significant bit)

BIT-2

This is a single numeric field indicating the value of bit 2 (where bit 1 is the least significant bit)

BIT-3 BIT-4 BIT-5 BIT-6 BIT-7 BIT-8

These are single numeric fields indicating the value of bits 3 through 8 (where bit 1 is the least significant bit)

Remarks

This function can be used to check whether a bit is set/unset in an alphanumeric or numeric byte.

See the following example decimal values and the values in BIT-X(nn) and BIT-x

Decimal 000 001 002 003 127 255

BIT-X(1) BIT-8 0 0 0 0 0 1

BIT-X(2) BIT-7 0 0 0 0 1 1

BIT-X(3) BIT-6 0 0 0 0 1 1

BIT-X(4) BIT-5 0 0 0 0 1 1

BIT-X(5) BIT-4 0 0 0 0 1 1

BIT-X(6) BIT-3 0 0 0 0 1 1

BIT-X(7) BIT-2 0 0 1 1 1 1

BIT-X(8) BIT-1 0 1 0 1 1 1

Sample code

* Verify that decimal zero has a zero in the lowest bit

MOVE 000 TO INPUT-BYTE-COMPX.

PERFORM UNPACK-INPUT-BYTE.

IF BIT-1 = ZERO

GO TO AS-EXPECTED

ELSE

GO TO UNEXPECTED.

* Verify that decimal 255 has a 1 in the lowest bit

MOVE 255 TO INPUT-BYTE-COMPX.

PERFORM UNPACK-INPUT-BYTE.

IF BIT-1 = 1

GO TO AS-EXPECTED

ELSE

GO TO UNEXPECTED.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard


UPDATE-JOB-LOGGING

The UPDATE-JOB-LOGGING function switches on job logging for this program if it has not already been switched on. This is typically automatically used by the browse programs when any maintenance is performed as the browses do not output job logging information unless a maintenance function is performed.

Input parameters

none

Output parameters

none

Remarks

Most programs automatically create a job logging record when they first load. This is only disabled by moving N to WW-CHECK-ACCESS before using PROBEGIN.PRO. If your program suppresses the output of job logging information in this way it can create the job logging record later using this function.

Job logging is enabled/disabled against the Company setup program. This function has no effect unless job logging is enabled for the company.

Sample code

PERFORM UPDATE-JOB-LOGGING.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: Standard


UPDATE-SYSTEM-DATE-CCYYMMDD

The UPDATE-SYSTEM-DATE-CCYYMMDD function provides a quick and convenient way to read the current server operating system date and move this to the field SYSTEM-DATE-CCYYMMDD.

Input parameters

none

Output parameters

SYSTEM-DATE-CCYYMMDD

This field is updated with the current server operating system date in CCYYMMDD format.

IM0DAT

This field is updated with the current server operating system date in normal date format.

Remarks

This function can be performed at any time to read the current server operating system date and move it to the two standard linkage fields.

Many programs use one or other of these fields as the default date.

This could be used by a program to ensure that a long-running process always uses the correct system date.

Sample code

IF NEW-ORDER-PROCESS = "Y"

PERFORM UPDATE-SYSTEM-DATE-CCYYMMDD.

Requirements

Version: Included in SYSPRO 6.0 Issue 010 and later

Copybooks: Standard


VERIFY-ACCESS

The VERIFY-ACCESS function is used to verify whether the operator is allowed access to a specific type of code, field or activity.

The system administrator can define which warehouses, A/R and A/P branches, banks, activities, fields, salespersons and job classifications can be accessed by each operator - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

It is recommended that you use the specific functions to verify access such as VERIFY-ACCESS-WH and VERIFY-ACCESS-FIELD rather than this function.

Input parameters

WW-ACCESS-FIELD

The code to be tested.

WW-ACCESS-NUM

The number of the field or activity to be tested

WW-ACCESS-TYPE

The access type:

1 – Warehouse

2 – A/R Branch

3 – A/P Branch

4 – Bank

5 – Activity

6 – Field

7 – Salesperson

8 - Job Classification

9 - CMS Account

10 - CMS Contact

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses a warehouse, branch, bank, salesperson, job classification or one of the protected activities or fields the program must verify whether access is allowed.

It is recommended to use the individual routines as follows:

VERIFY-ACCESS-WH

VERIFY-ACCESS-ARBR

VERIFY-ACCESS-APBR

VERIFY-ACCESS-BANK

VERIFY-ACCESS-TT

VERIFY-ACCESS-FIELD

VERIFY-ACCESS-REP

VERIFY-ACCESS-JOBCL

VERIFY-ACCESS-ACCOUNT

VERIFY-ACCESS-CONTACT

If the access has been denied then a message box will be displayed.

Sample code

MOVE 1 TO WW-ACCESS-TYPE. *> Warehouse

MOVE INVWHS-WH TO WW-ACCESS-FIELD.

PERFORM VERIFY-ACCESS.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS-WH, VERIFY-ACCESS-ARBR, VERIFY-ACCESS-APBR, VERIFY-ACCESS-BANK, VERIFY-ACCESS-TT, VERIFY-ACCESS-FIELD, VERIFY-ACCESS-REP, VERIFY-ACCESS-JOBCL, VERIFY-ACCESS-ACCOUNT, VERIFY-ACCESS-CONTACT


VERIFY-ACCESS-ACCOUNT

The VERIFY-ACCESS-ACCOUNT function is used to verify whether the operator is allowed access to a CMS Account. The Account uses the Salesperson, AR branch and Account type as a filter. The system administrator can define which account types can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

Must be cleared before the rest of the fields are populated.

WW-ACCESS-ACC-SLS

The Salesperson from the account (CRMACC-SLSP).

WW-ACCESS-ACC-BRN

The Branch from the account (CRMACC-BR).

WW-ACCESS-ACC-TYP

The Account type from the account (CRMACC-TYPE).

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses a Contact Management Account this routine should be used to verify whether the operator has access to the Account.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-ACCOUNT.

Sample code

*

** Check Account security

MOVE SPACES TO WW-ACCESS-FIELD.

MOVE D-SALESPERSON TO WW-ACCESS-ACC-SLS.

MOVE D-BRANCH TO WW-ACCESS-ACC-BRN.

MOVE D-ACC-TYPE TO WW-ACCESS-ACC-TYP.

PERFORM VERIFY-ACCESS-ACCOUNT.

IF WW-ACCESS-OK <> "Y"

GO TO ENDJOB.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP2 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-ACCOUNT


VERIFY-ACCESS-APBR

The VERIFY-ACCESS-APBR function is used to verify whether the operator is allowed access to the passed AP branch code. The system administrator can define which branches can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

The AP branch to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses an AP branch code this routine should be used to determine whether the current operator or role has access to the branch.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-APBR.

Sample code

MOVE APSMST-ACL TO WW-ACCESS-FIELD.

PERFORM VERIFY-ACCESS-APBR.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-APBR


VERIFY-ACCESS-ARBR

The VERIFY-ACCESS-ARBR function is used to verify whether the operator is allowed access to the passed AR branch code. The system administrator can define which branches can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

The AR branch to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses an AR branch code this routine should be used to determine whether the current operator or role has access to the branch.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-ARBR.

Sample code

MOVE ARSMST-BR TO WW-ACCESS-FIELD.

PERFORM VERIFY-ACCESS-ARBR.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-ARBR


VERIFY-ACCESS-BANK

The VERIFY-ACCESS-BANK function is used to verify whether the operator is allowed access to the passed bank code. The system administrator can define which banks can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

The bank to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses a bank code this routine should be used to determine whether the current operator or role has access to the bank.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-BANK.

Sample code

MOVE ARSMST-VBK TO WW-ACCESS-FIELD.

PERFORM VERIFY-ACCESS-BANK.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

FILTER-ACCESS, FILTER-ACCESS-BANK


VERIFY-ACCESS-CONTACT

The VERIFY-ACCESS-CONTACT function is used to verify whether the operator is allowed access to a CMS Contact. The Contact uses the Property, Class, Type, Category and Territory as a filter. The system administrator can define which Property, Class, Type, Category and Territories can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

Must be cleared before the rest of the fields are populated.

WW-ACCESS-CON-PRP

The Property from the contact (CRMCON-PROPERTY).

WW-ACCESS-CON-CLS

The Class from the contact (CRMCON-CLASS).

WW-ACCESS-CON-TYP

The Type from the contact (CRMCON-TYPE).

WW-ACCESS-CON-CAT

The Category from the contact (CRMCON-CAT).

WW-ACCESS-CON-TER

The Territory from the contact (CRMCON-TERRITORY).

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses a Contact Management Contact this routine should be used to verify whether the operator has access to the Contact.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-CONTACT.

Sample code

*

** Contact Security

MOVE SPACES TO WW-ACCESS-FIELD

MOVE D-PROPERTY TO WW-ACCESS-CON-PRP

MOVE D-CLASS TO WW-ACCESS-CON-CLS

MOVE D-TYPE TO WW-ACCESS-CON-TYP

MOVE D-CAT TO WW-ACCESS-CON-CAT

MOVE D-TERRITORY TO WW-ACCESS-CON-TER

PERFORM VERIFY-ACCESS-CONTACT

IF WW-ACCESS-OK <> "Y"

GO TO ENDJOB.

Requirements

Version: Included in SYSPRO 6.0 issue 010 SP2 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-CONTACT


VERIFY-ACCESS-FIELD

The VERIFY-ACCESS-FIELD function is used to verify whether the operator is allowed access to a specific field. The system administrator can define which fields can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-NUM

The field to be tested. See IMPSEC.IMP for a list of fields.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses one of the listed fields in the operator or role maintenance program this routine should be used to determine whether the current operator has access to the field.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-FIELD.

Sample code

MOVE 1 TO WW-ACCESS-NUM. *> A/R credit limit

PERFORM VERIFY-ACCESS-FIELD.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-FIELD


VERIFY-ACCESS-JOBCL

The VERIFY-ACCESS-JOBCL function is used to verify whether the operator is allowed access to the passed job classification. The system administrator can define which job classifications can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

The job classification to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses a job this routine should be used to determine whether the current operator or role has access to the job classification.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-JOBCL.

Sample code

MOVE WIPMST-CLS TO WW-ACCESS-FIELD.

PERFORM VERIFY-ACCESS-JOBCL.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.1 issue 004 and later

Copybooks: standard

See also

FILTER-ACCESS, FILTER-ACCESS-JOBCL


VERIFY-ACCESS-REP

The VERIFY-ACCESS-REP function is used to verify whether the operator is allowed access to a specific salesperson code. The system administrator can define which salespersons can be accessed by each operator - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

The salesperson to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses a salesperson this routine should be used to determine whether the current operator code has access to the salesperson.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-REP.

Sample code

MOVE ARSMST-SLSP TO WW-ACCESS-FIELD.

PERFORM VERIFY-ACCESS-REP.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-REP


VERIFY-ACCESS-TT

The VERIFY-ACCESS-TT function is used to verify whether the operator is allowed access to an activity. The system administrator can define which activities can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-NUM

The activity to be tested. See IMPSEC.IMP for a list of activities.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses one of the listed activities in the operator or role maintenance program this routine should be used to determine whether the current operator has access to the activity.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-TT.

Sample code

MOVE 1 TO WW-ACCESS-NUM. *> Stock receipts

PERFORM VERIFY-ACCESS-TT.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-TT


VERIFY-ACCESS-WH

The VERIFY-ACCESS-WH function is used to verify whether the operator is allowed access to the passed warehouse code. The system administrator can define which warehouses can be accessed by each operator or role - it is the programs' responsibility to check the access. If access is denied then this function will display an Access denied message box and a flag is returned.

Input parameters

WW-ACCESS-FIELD

The warehouse to be tested.

Output parameters

WW-ACCESS-OK

A flag indicating whether the access is allowed.

Y – Yes access is allowed

D-S-ERROR

The message 'ACCESS DENIED' indicates the operator has been denied access.

Remarks

Whenever a program accesses a warehouse code this routine should be used to determine whether the current operator or role has access to the warehouse.

If access has been denied then a message box will be displayed. If you want to simply check whether access is allowed without displaying a message then use FILTER-ACCESS-WH.

Sample code

MOVE INVWHS-WH TO WW-ACCESS-FIELD.

PERFORM VERIFY-ACCESS-WH.

IF WW-ACCESS-OK NOT = "Y"

GO TO ACCESS-DENIED-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later

Copybooks: standard

See also

VERIFY-ACCESS, FILTER-ACCESS-WH


VERIFY-PASSWORD

The VERIFY-PASSWORD function is used to verify a password that has been requested by your application against a previously set password.

This function is part of the generic password system that provides various functions to assist developers to control and verify passwords in a consistent manner. These passwords are stored in an encrypted format.

Input parameters

LINK-PASS-TYP

This is a 6 character password type to identify the type of password being verified.

For example the operator password uses ADMOPR.

It is recommended that third party systems use a password type beginning with USR.

LINK-PASS-CMP

This is the company id of the key required.

Note that if you move in spaces to this field then the current company id will be used. The only exception to this is when the operator file ('ADMOPR' in LINK-PASS-TYP) when the company id is always taken as blank.

LINK-PASS-KEY

This is the key of the item being protected.

For example when verifying the operator password this will be the operator code.

If you wish to verify a password that is function based – you should move spaces to this field.

LINK-PASS-ENT

This is the unencrypted version of the password that the user has entered in your application. It can be up to 30 characters long.

Output parameters

LINK-PASS-OK

This flag indicates whether the operator entered a valid password.

Spaces – Yes

E – password expired (operator passwords)

N – Password was not verified

Remarks

The password system provides various functions to allow developers to set and verify passwords in a consistent manner. These passwords are encrypted using a proprietary algorithm that uses the password type, a key field and the entered password. It is not possible to unencrypt a password using this system.

The VERIFY-PASSWORD function allows a password prompted in your application to be verified against a previously defined password. The system will verify the password and return a flag indicating whether the password was entered successfully. If the password is incorrect this function will display an appropriate message.

The ASK-PASSWORD function is more commonly use by systems wishing the check a password however existing systems often already prompt the operator for the password – in this case this function is more useful.

Sample code

* Test the password for changing the price against a S/Order line

MOVE SPACES TO LINK-PASS.

MOVE "-SOR03" TO LINK-PASS-TYP. *> See IMPPSS.IMP for codes

MOVE D-ENTERED-PASS TO LINK-PASS-ENT.*> Entered password

PERFORM VERIFY-PASSWORD.

IF LINK-PASS-OK = SPACES

MOVE SPACES TO LINK-PASS

GO TO PASSWORD-ENTERED-CORRECTLY

ELSE

MOVE SPACES TO LINK-PASS

GO TO ABORT-FUNCTION.

Requirements

Version: Included in Encore 5.0 and later. The program functions are password protected using this system from SYSPRO 6.0 issue 009 and later.

Copybooks: standard

See also

password system, ASK-PASSWORD, SET-PASSWORD, SET-PASSWORD-NO-OLD, SET-PASSWORD-NO-ASK, GET-PASSWORD-INFO, ADD-PASSWORD-CTL, DEL-PASSWORD


WRITE-PRLINE-AFTER-1

The WRITE-PRLINE-AFTER-1 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of one line.

This function forms part of the generic Printing functions that provide a simple and consistent way of printing to any of the different printer types supported.

The programmer must use PRINT-OPEN to initialise the generic printer functions, any number of text lines can be written to the report. Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

In addition you can pass a set of print offsets that allow special formatting to be applied. These are used where potentially large numeric fields can be printed but an existing layout that caters for smaller fields is to be retained.

Input parameters

SP-PRLINE

This field is used to pass the text to be printed. It is assumed that each character is the same width therefore you should use spaces to ensure columns are spaced correctly.

Most standard SYSPRO reports print up to 132 characters on a print line although you can use up to 300 characters per line.

Most reports format and pass a single line of text for printing at a time however you may pass up to 6 lines of 300 characters for printing. To use more than one line use SP-PRLINE-1(n) where n is 1-6.

SP-LINE-PROTECT

This field defines whether the text to be printed must not be orphaned at the bottom of a page when subsequent text is formatted around this text.

This is often used when a report has a subheading and you do not want the subheading to appear as the last line on a page.

Move in the number of lines that must be free at the bottom of the page. If there is not this many lines free then a head of form will be issued before the text is printed.

SP-PRINT-OFFSETS

This field allows you to pass a table of print offsets.

Output parameters

SP-LINE-COUNT

This field is maintained by the system and is the number of lines printed on the current page.

SP-PAGE-COUNT

This field is maintained by the system and is the current page number.

SP-PRLINE

This field is initialised to LOW-VALUES after the function.

Remarks

Remember to issue a PRINT-OPEN function before trying to print any text using the generic print routines. After printing you must finalise the report with the PRINT-CLOSE function.

See the PRINT-OPEN function for details of the different types of printer supported and other information including how the line count is maintained.

To print a line of text move the text to the field SP-PRLINE and then use WRITE-PRLINE-AFTER-1. This performs a single line skip (from the current/previous line) and then prints the current line of text. There are additional functions WRITE-PRLINE-AFTER-2, WRITE-PRLINE-AFTER-3 etc up to 9.

In addition you can move the number of lines to be skipped to the field SP-LINE-SKIP and the use WRITE-PRLINE-AFTER-SKIP.

The function WRITE-PRLINE-AFTER-PAGE should be used to force a page skip before printing the line of text.

Sample code

MOVE "Demonstration report" TO L-PRT-TITLE.

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

MOVE "Second line of text" TO SP-PRLINE.

MOVE 1 TO SP-LINE-SKIP.

PERFORM WRITE-PRLINE-AFTER-SKIP.

*

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, print offsets, PRINT-OPEN, WRITE-PRLINE-AFTER-SKIP, WRITE-PRLINE-AFTER-1, WRITE-PRLINE-AFTER-PAGE, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-2

The WRITE-PRLINE-AFTER-2 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of two lines.

This function forms part of the generic Printing functions that provide a simple and consistent way of printing to any of the different printer types supported.

The programmer must use PRINT-OPEN to initialise the generic printer functions, any number of text lines can be written to the report. Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

In addition you can pass a set of print offsets that allow special formatting to be applied. These are used where potentially large numeric fields can be printed but an existing layout that caters for smaller fields is to be retained.

Input parameters

SP-PRLINE

This field is used to pass the text to be printed. It is assumed that each character is the same width therefore you should use spaces to ensure columns are spaced correctly.

Most standard SYSPRO reports print up to 132 characters on a print line although you can use up to 300 characters per line.

Most reports format and pass a single line of text for printing at a time however you may pass up to 6 lines of 300 characters for printing. To use more than one line use SP-PRLINE-1(n) where n is 1-6.

SP-LINE-PROTECT

This field defines whether the text to be printed must not be orphaned at the bottom of a page when subsequent text is formatted around this text.

This is often used when a report has a subheading and you do not want the subheading to appear as the last line on a page.

Move in the number of lines that must be free at the bottom of the page. If there is not this many lines free then a head of form will be issued before the text is printed.

SP-PRINT-OFFSETS

This field allows you to pass a table of print offsets.

Output parameters

SP-LINE-COUNT

This field is maintained by the system and is the number of lines printed on the current page.

SP-PAGE-COUNT

This field is maintained by the system and is the current page number.

SP-PRLINE

This field is initialised to LOW-VALUES after the function.

Remarks

Remember to issue a PRINT-OPEN function before trying to print any text using the generic print routines. After printing you must finalise the report with the PRINT-CLOSE function.

See the PRINT-OPEN function for details of the different types of printer supported and other information including how the line count is maintained.

To print a line of text move the text to the field SP-PRLINE and then use WRITE-PRLINE-AFTER-1. This performs a single line skip (from the current/previous line) and then prints the current line of text. There are additional functions WRITE-PRLINE-AFTER-2, WRITE-PRLINE-AFTER-3 etc up to 9.

In addition you can move the number of lines to be skipped to the field SP-LINE-SKIP and the use WRITE-PRLINE-AFTER-SKIP.

The function WRITE-PRLINE-AFTER-PAGE should be used to force a page skip before printing the line of text.

Sample code

MOVE "Demonstration report" TO L-PRT-TITLE.

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

MOVE "Second line of text" TO SP-PRLINE.

MOVE 1 TO SP-LINE-SKIP.

PERFORM WRITE-PRLINE-AFTER-SKIP.

*

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, print offsets, PRINT-OPEN, WRITE-PRLINE-AFTER-SKIP, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-3

The WRITE-PRLINE-AFTER-3 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of three lines.

See the function WRITE-PRLINE-AFTER-1 for more details.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-4

The WRITE-PRLINE-AFTER-4 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of four lines.

See the function WRITE-PRLINE-AFTER-1 for more details.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-5

The WRITE-PRLINE-AFTER-5 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of five lines.

See the function WRITE-PRLINE-AFTER-1 for more details.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-6

The WRITE-PRLINE-AFTER-6 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of six lines.

See the function WRITE-PRLINE-AFTER-1 for more details.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-7

The WRITE-PRLINE-AFTER-7 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of seven lines.

See the function WRITE-PRLINE-AFTER-1 for more details.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-8

The WRITE-PRLINE-AFTER-8 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of eight lines.

See the function WRITE-PRLINE-AFTER-1 for more details.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-9

The WRITE-PRLINE-AFTER-9 function is used to call the WRITE-PRLINE-AFTER-SKIP function with a fixed line skip of nine lines.

See the function WRITE-PRLINE-AFTER-1 for more details.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WRITE-PRLINE-AFTER-PAGE

The WRITE-PRLINE-AFTER-PAGE function is used to print text on a document or report after issuing a page skip. This will ensure that the text is printed at the very top of the next page.

This function forms part of the generic Printing functions that provide a simple and consistent way of printing to any of the different printer types supported.

The programmer must use PRINT-OPEN to initialise the generic printer functions, any number of text lines can be written to the report. Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

Input parameters

SP-PRLINE

This field is used to pass the text to be printed. It is assumed that each character is the same width therefore you should use spaces to ensure columns are spaced correctly.

Most standard SYSPRO reports print up to 132 characters on a print line although you can use up to 300 characters per line.

Most reports format and pass a single line of text for printing at a time however you may pass up to 6 lines of 300 characters for printing. To use more than one line use SP-PRLINE-1(n) where n is 1-6.

SP-HOF-BOLD

This field can be set to Y to indicate that you want the text to be printed in bold. See the remarks below.

Output parameters

SP-LINE-COUNT

This field is maintained by the system and is the number of lines printed on the current page.

SP-PAGE-COUNT

This field is maintained by the system and is the current page number.

SP-PRLINE

This field is initialised to LOW-VALUES after the function.

Remarks

Remember to issue a PRINT-OPEN function before trying to print any text using the generic print routines. After printing you must finalise the report with the PRINT-CLOSE function.

See the PRINT-OPEN function for details of the different types of printer supported and other information including how the line count is maintained.

This function is typically used within a HOF routine to force a page skip and to print the first line of the page headings. The HOF routine is called automatically by the generic print routines whenever a new page is required.

Everything printed within a HOF routine is automatically bolded however if you need to use this function outside of a HOF routine and still wish the text printed to be bolded then you can move Y to SP-HOF-BOLD. In this case you should then use the PRINT-HOF-UNDERLINE function to clear the bold and draw an underline.

Sample code

HOF.

MOVE SP-PAGE-COUNT TO PRPAGE.

MOVE HDG1 TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

MOVE HDG2 TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV, PRINT-HOF-UNDERLINE


WRITE-PRLINE-AFTER-SKIP

The WRITE-PRLINE-AFTER-SKIP function is used to print text on a document or report. This function forms part of the generic Printing functions that provide a simple and consistent way of printing to any of the different printer types supported.

The programmer must use PRINT-OPEN to initialise the generic printer functions, any number of text lines can be written to the report. Using PRINT-CLOSE will complete the printing and for most printer types actually initiates the previewing and/or printing of the report.

When using Windows printing it is possible to include a bitmapped background – often used with documents such as invoices and statements.

In addition you can pass a set of print offsets that allow special formatting to be applied. These are used where potentially large numeric fields can be printed but an existing layout that caters for smaller fields is to be retained.

Input parameters

SP-PRLINE

This field is used to pass the text to be printed. It is assumed that each character is the same width therefore you should use spaces to ensure columns are spaced correctly.

Most standard SYSPRO reports print up to 132 characters on a print line although you can use up to 300 characters per line.

Most reports format and pass a single line of text for printing at a time however you may pass up to 6 lines of 300 characters for printing. To use more than one line use SP-PRLINE-1(n) where n is 1-6.

SP-LINE-SKIP

This field defines how many line skips will be issued before the text in SP-PRLINE is printed. The default is one. The routines WRITE-PRLINE-AFTER-2 etc can be used where a fixed skip is required.

SP-LINE-PROTECT

This field defines whether the text to be printed must not be orphaned at the bottom of a page when subsequent text is formatted around this text.

This is often used when a report has a subheading and you do not want the subheading to appear as the last line on a page.

Move in the number of lines that must be free at the bottom of the page. If there is not this many lines free then a head of form will be issued before the text is printed.

SP-PRINT-OFFSETS

This field allows you to pass a table of print offsets.

Output parameters

SP-LINE-COUNT

This field is maintained by the system and is the number of lines printed on the current page.

SP-PAGE-COUNT

This field is maintained by the system and is the current page number.

SP-PRLINE

This field is initialised to LOW-VALUES after the function.

Remarks

Remember to issue a PRINT-OPEN function before trying to print any text using the generic print routines. After printing you must finalise the report with the PRINT-CLOSE function.

See the PRINT-OPEN function for details of the different types of printer supported and other information including how the line count is maintained.

To print a line of text move the text to the field SP-PRLINE and then use WRITE-PRLINE-AFTER-1. This performs a single line skip (from the current/previous line) and then prints the current line of text. There are additional functions WRITE-PRLINE-AFTER-2, WRITE-PRLINE-AFTER-3 etc up to 9.

In addition you can move the number of lines to be skipped to the field SP-LINE-SKIP and the use WRITE-PRLINE-AFTER-SKIP.

The function WRITE-PRLINE-AFTER-PAGE should be used to force a page skip before printing the line of text.

Sample code

MOVE "Demonstration report" TO L-PRT-TITLE.

PERFORM PRINT-OPEN.

*

MOVE "First line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-PAGE.

*

MOVE "Second line of text" TO SP-PRLINE.

MOVE 1 TO SP-LINE-SKIP.

PERFORM WRITE-PRLINE-AFTER-SKIP.

*

MOVE "Third line of text" TO SP-PRLINE.

PERFORM WRITE-PRLINE-AFTER-1.

*

MOVE MSG-END-OF-REPORT TO SP-PRLINE. *> End of report

PERFORM WRITE-PRLINE-AFTER-2.

*

PERFORM PRINT-CLOSE.

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Printing, print offsets, PRINT-OPEN, WRITE-PRLINE-AFTER-1, PRINT-CLOSE, PRINT-CLOSE-NO-PRINT, SERV


WW

The WW function is a generic call to the IMPSTD support program. The WW function is used internally by many of the other common routines and should not be called directly by a user program.

Input parameters

WW-FUNCTION

The function to be performed. Other parameters passed depending on the function.

Output parameters

Various

Remarks

It is recommended that this function is not executed directly by a user program as the functions are subject to change.

Sample code

none

Requirements

Version: Included in Encore 5.0 and later.

Copybooks: standard

See also

Functions by name, Functions by type


X91-SCAN-COMPLETE

The X91-SCAN-COMPLETE function is used to indicate that the directory scanning functions are completed. It is highly recommended that you use this function before starting another directory scanning task.

For a complete description of this function see the topic Searching for Files.

Input parameters

none

Output parameters

none

Remarks

This function should be used to indicate that the current directory scanning function has been completed.

Note that if you have started scanning a directory using X91-SCAN-DIRECTORY and want to 'cancel' or 'terminate' this scanning process then you must use the X91-SCAN-TERMINATE-EARLY function before using this function.

Sample code

* Prepare directory scanning logic.

PERFORM X91-SCAN-INITIALIZE.

COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY + X91-ATT-ARCHIVED.

MOVE "*.EXE" TO X91-SCAN-FILEIN.

GET-NEXT-FILE.

PERFORM X91-SCAN-DIRECTORY.

IF X91-STATUS = ZERO

PERFORM PROCESS-SCAN-FILEOUT

IF CONTINUE-LOOP = "Y"

GO TO GET-NEXT-FILE

ELSE
PERFORM X91-SCAN-TERMINATE-EARLY.

PERFORM X91-SCAN-COMPLETE.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later

Copybooks: Standard

See also

Searching for Files, X91-SCAN-DIRECTORY, X91-SCAN-TERMINATE-EARLY, CHECK-FILE-EXISTS, CHECK-FILE-EXISTS-ON-CLIENT


X91-SCAN-DIRECTORY

The X91-SCAN-DIRECTORY is used to retrieve the first and subsequent files that match the specified name and attributes specified. This function can return both files and sub-directory names.

For a complete description of this function see the topic Searching for Files.

Input parameters

X91-FILEIN

Filename (including path and wildcards) to be matched on the server in a client/server environment.

This is case sensitive on Unix servers.

Note that spacey file names must be quoted.

X91-ATTRIN

This field contains a combination of the attributes that are to be included in the match. By default all normal files will be included. In addition you can sum one or more of the following 78 levels

78 X91-ATT-READ-ONLY VALUE 1.

78 X91-ATT-HIDDEN VALUE 2.

78 X91-ATT-SYSTEM VALUE 4.

78 X91-ATT-VOLUME-LABEL VALUE 8.

78 X91-ATT-SUB-DIRECTORY VALUE 16.

78 X91-ATT-ARCHIVED VALUE 32.

For example COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY + X91-ATT-ARCHIVED will return, Normal, Read-only and Archived files or any files with 1 or more of these attributes.

X91-IGNORE-HID-SYS

Set this flag to '1' (the default) to indicate that files with both the Hidden and System attributes are to be ignored from the result set. These files typically are reserved for operating system special usage.

1 - ignore hidden+system

0 - do not check the hidden or system attribute

X91-IGNORE-DIRS

Set this flag to '1' (the default) to indicate that sub-directories are to be ignored from the result set.

1 - ignore sub-directories

0 - return sub-directories that match the naming and attributes specified.

X91-IGNORE-FILES

Set this flag to '1' (not the default) to indicate that normal files are to be ignored from the result set. The default value of '0' indicates that files are to be included.

1 - ignore files

0 - return files that match the naming and attributes specified.

X91-IGNORE-DOT-DOT

Set this flag to '1' (the default) to indicate that directories with the special '.' and '..' names are to be ignored from the result set. These directories have special meaning to the operating system and are generally not required.

1 - ignore '.' and '..'

0 - allow '.' and '..' directory names to be returned

X91-GET-DATETIME

Set this flag to '1' (not the default) to indicate that the date and time that the file was last updated is to be unpacked into an easy-to-use format.

1 - unpack date and time

0 - do not unpack the date and time fields

Output parameters

X91-STATUS

This indicates the status of the X91-SCAN-DIRECTORY function.

0 - OK (more files can be returned)

1 - End of file list (use the X91-SCAN-COMPLETE function)

2 - Error (use the X91-SCAN-COMPLETE function)

X91-FILEOUT

This field contains a single matched filename. Note that this filename does not contain any path.

X91-SIZE

This field contains the disk file size in bytes of the matched file.

X91-DATE

The date that the file was created in a packed format.

Note that if you set the value X91-GET-DATETIME to 1 the field X91-DATETIME-DATE will be populated in an easy-to-use format (see below).

X91-TIME

The time that the file was created in a packed format.

Note that if you set the value X91-GET-DATETIME to 1 the field X91-DATETIME-TIME will be populated in an easy-to-use format (see below).

X91-ATTROUT

This contains the logical OR of the file attribute. To make this easier to process in you program you can use on or more of the following X91-ATO logical fields.

88 X91-ATO-READ-ONLY.

88 X91-ATO-HIDDEN.

88 X91-ATO-SYSTEM.

88 X91-ATO-VOLUME-LABEL.

88 X91-ATO-SUB-DIRECTORY.

88 X91-ATO-ARCHIVED.

For example if you want to test whether the returned file is Read-only or Hidden then you can include the statement:

IF X91-ATO-READ-ONLY OR X91-ATO-HIDDEN

X91-DATETIME-DATE

The date that the file was last updated in CCYYMMDD format.

This field is only populated when you set the value X91-GET-DATETIME to 1.

X91-DATETIME-TIME

The time that the file was last updated in HHMMSS format. Note that the second field (SS) will only have even numbered seconds (0,2,4,6,..., 56, 58).

This field is only populated when you set the value X91-GET-DATETIME to 1.

Remarks

This function is used to retrieve the first and then subsequent file/sub-directory names that match the name (including wildcards) and attributes provided.

This function should be preceded by the X91-SCAN-INITIALIZE function and is typically executed in a loop until the status (X91-STATUS) is non-zero. Then the X91-SCAN-COMPLETE function should be performed.

Note that if you wish to stop retrieving files using this function before the end-of-list status is returned then you must perform the X91-SCAN-TERMINATE-EARLY function to release any system resources

Sample code

* Prepare directory scanning logic.

PERFORM X91-SCAN-INITIALIZE.

COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY + X91-ATT-ARCHIVED.

MOVE 1 TO X91-GET-DATETIME. *> we want the date/time last updated

MOVE "*.EXE" TO X91-SCAN-FILEIN.

GET-NEXT-FILE.

PERFORM X91-SCAN-DIRECTORY.

IF X91-STATUS = ZERO

PERFORM PROCESS-SCAN-FILEOUT

IF CONTINUE-LOOP = "Y"

GO TO GET-NEXT-FILE

ELSE
PERFORM X91-SCAN-TERMINATE-EARLY.

PERFORM X91-SCAN-COMPLETE.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later

Copybooks: Standard

See also

Searching for Files, X91-SCAN-INITIALIZE, 91-SCAN-TERMINATE-EARLY, X91-SCAN-COMPLETE, CHECK-FILE-EXISTS, CHECK-FILE-EXISTS-ON-CLIENT


X91-SCAN-INITIALIZE

The X91-SCAN-INITIALIZE function is used to initiate the directory scanning function. This function should be performed before any of the other directory scanning functions or fields are referenced.

For a complete description of this function see the topic Searching for Files.

Input parameters

none

Output parameters

X91-DETAILS

These fields are initialized ready for use with the X91-SCAN-DIRECTORY function.

Remarks

This function initializes the working fields in STANDARD.WRK. This should be performed before any of the other directory scanning functions or fields are referenced.

After performing this function you would typically define the attributes and file names to be matched before calling the X91-SCAN-DIRECTORY function.

Sample code

* Prepare directory scanning logic.

PERFORM X91-SCAN-INITIALIZE.

COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY + X91-ATT-ARCHIVED.

MOVE "*.EXE" TO X91-SCAN-FILEIN.

GET-NEXT-FILE.

PERFORM X91-SCAN-DIRECTORY.

IF X91-STATUS = ZERO

PERFORM PROCESS-SCAN-FILEOUT

IF CONTINUE-LOOP = "Y"

GO TO GET-NEXT-FILE

ELSE
PERFORM X91-SCAN-TERMINATE-EARLY.

PERFORM X91-SCAN-COMPLETE.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later

Copybooks: Standard

See also

Searching for Files, X91-SCAN-DIRECTORY, CHECK-FILE-EXISTS, CHECK-FILE-EXISTS-ON-CLIENT


X91-SCAN-TERMINATE-EARLY

The X91-SCAN-TERMINATE-EARLY function is used to terminate the directory scanning process before the X91-SCAN-DIRECTORY has returned an end-of-list (non-zero) status.

For a complete description of this function see the topic Searching for Files.

Input parameters

none

Output parameters

none

Remarks

This function should be used to return any system resources used during the directory scanning process.

Note that you should not use this function if a non-zero status is returned from the X91-SCAN-DIRECTORY function.

Sample code

* Prepare directory scanning logic.

PERFORM X91-SCAN-INITIALIZE.

COMPUTE X91-ATTRIN = X91-ATT-READ-ONLY + X91-ATT-ARCHIVED.

MOVE "*.EXE" TO X91-SCAN-FILEIN.

GET-NEXT-FILE.

PERFORM X91-SCAN-DIRECTORY.

IF X91-STATUS = ZERO

PERFORM PROCESS-SCAN-FILEOUT

IF CONTINUE-LOOP = "Y"

GO TO GET-NEXT-FILE

ELSE
PERFORM X91-SCAN-TERMINATE-EARLY.

PERFORM X91-SCAN-COMPLETE.

Requirements

Version: Included in SYSPRO 6.0 issue 009 and later

Copybooks: Standard

See also

Searching for Files, X91-SCAN-DIRECTORY, CHECK-FILE-EXISTS, CHECK-FILE-EXISTS-ON-CLIENT