Microsoft Windows 16-bit

Requirements

An obsolete version of the PI-API exists for 16-bit Microsoft Windows. PI-API-MSW runs under Microsoft Windows 3.1 and Windows for Workgroups 3.11. It requires that the PC communicate with PI on Open VMS using either the DECNet or TCP/IP protocol. Communication with PI on Windows NT or UNIX is supported only using TCP/IP protocol.

The following PC network software is supported by PI-API-MSW:

Protocol Software DLL
Pathworks v5.0 (DECNet and TCP/IP) pisck.dll
FTP PC/TCP v2.2 pisck.dll
Wollongong Pathway release 1.2 pisck.dll
Novell LAN Workplace v4.1 pisck.dll
Microsoft TCP/IP - 32 v3.11a pisck.dll
Pathworks TCP/IP v2.0 pitcp.dll
WRQ TCP Connection v2.01 pitcp.dll

Current users of Pathworks DECNet v4.1 can still connect with the pidnt.dll however the software has known problems and users are advised to upgrade to Pathworks v5.0 or select a different software package.

TCP/IP has become the de facto network communication standard and is recommended for communication with PI. It is compatible with all PI platforms and is being delivered with the operating system on PC’s running Windows 9x or Windows NT.

Users of the PI-API-MSW must be familiar with writing 16-bit Windows applications and the programming tools necessary to create these programs. Some examples of Windows development tools are:

Installation

Installation is described below. Please consult the release notes delivered in electronic format (readme.txt) for the latest information as well as bug fixes and enhancements.

Create a PI directory in your fixed disk called PIPC. This is typically called C:\PIPC although any directory name is suitable. If you have previously installed PI client software (PI-ProcessBook, PI-PC) you should install the PI-API software in your existing PIPC directory. This directory is referred to as PIHOME

If you already have PI client software installed, copy your current client initialization files to a safe place. These files are called piclient.ini and pilogin.ini and are in your PIHOME\DAT directory. If you fail to do this, you will lose your initialization settings for your existing PI client software when you install the PI-API files below. Note that you may not have a piclient.ini file. This file was used in earlier versions of the PI-API but is still supported.

Install PI-API-MSW by simply executing the self-extracting zip file distributed on the PI-API CD-ROM.

d:> w16v1234.exe

Choose the installation directory for the unzip operation. Then you may restore your original pilogin.ini and piclient.ini files that you may have moved away as described earlier.

The distribution disk contains these directories and files:

README.TXT      
DAT      
  PILOGIN.INI    
EXAMPLES      
  BASIC    
    MANINPUT  
      DISPLAY.FRM
      MANINPUT.BAS
      MANINPUT.ICO
      MANINPUT.MAK
      SEARCH.FRM
      SPLASH.BMP
      SPLASH.FRM
    MONITOR  
      MONITOR.FRM
      MONITOR.ICO
      MONITOR.MAK
      SPLASH.BMP
      SPLASH.FRM
  C    
    APISNAP.C  
    APISNAP.MAK  
    APISNAP.DEF  
INCLUDE      
  PIAPI.BAS    
  PIAPI.H    
  PIAPIX.H    
  PIBA.H    
  PIDEFS.H    
  PIDGSTAT.H    
  PIGRIDTP.H    
  PILOGEX.H    
  PISQL.H    
  PISTATUS.H    
  PIUTIL.BAS    
LIBRARY      
  PIAPI.LIB   Import library
  PIDNT.DLL   DECNet library
  PISCK.DLL   WinSock TCP/IP and Pathworks 5.x DECNet library
  PITCP.DLL   HP-Sockets TCP/IP library
  PILOGIN.DLL   PI Login Services library
  PILOGIN.LIB   Import library
  PILOGIN.HLP   PI Login Services help file

Location of DLLs

In order for executables linked with the PI-API libraries to run, the appropriate dynamic link libraries must be available to the application. Linked executables expect to load a DLL named piapi.dll and possibly pilogin.dll if the login services routines are also linked in. Three different versions of the piapi.dll are delivered in the PIPC\LIB directory: pidnt.dll; pitcp.dll; and pisck.dll. These support various network software packages. The appropriate library for the locally installed network software package should be copied to a location where the system can find it at runtime and renamed to piapi.dll.

It is recommended that these libraries, (piapi.dll and pilogin.dll) be installed in the directory PIPC\LIBRARY, (created above), and this directory be added to the PATH environment variable. If this proves unworkable (the PATH is already to long, the machine has multiple boot sequences, etc.) copy the libraries to the \WINDOWS\SYSTEM directory. To choose the appropriate version of the library to copy, consult the table at the beginning of this topic, which details supported network software. All WinSock compliant software should use the pisck.dll.

When an application calls functions located in a DLL Windows will attempt to search for DLLs in the current directory, the Windows directory, the Windows System Directory, the executable’s directory, and the user’s path as specified in the environment variable PATH. To ensure that the installed libraries, piapi.dll and pilogin.dll, are the ones being called, all of a system’s duplicate copies should be found and renamed. This may be done using the DOS dir command with the /s option starting at the root of each disk. For example:

c:

cd \

dir /s piapi.dll

would list all the piapi.dll files in the systems c: drive.

The Windows File Manager Search command (under the File menu) can also be used for this purpose.

Initialization files

PIPC.INI

If it does not currently exist, create a text file in the Windows directory called pipc.ini. This initialization file needs a section called PIPC with an entry for PIHOME. This PIHOME entry should point to the PIPC directory where PI-API-MSW is installed on the PC.

For example,

[PIPC]

PIHOME=C:\PIPC

This PIHOME entry specifies the location of the base directory from which the library finds other initialization files.

You may also add an entry for a network directory where a shared pilogin.ini file will reside within the DAT subdirectory. If you use this entry it will override the setting for PIHOME when the PI-API looks for the pilogin.ini file however the log file, pipc.log, will still be written in the DAT subdirectory of the directory identified by PIHOME

[PIPC]

PIHOME=C:\PIPC

PIPCSHARE=X:\NET\PI

Location of Initialization Files

An application built with PI-API-MSW looks for the initialization file called pilogin.ini and for backward compatibility also the file piclient.ini. These files contain server and port information to support default connection and connection to multiple PI servers. The library uses several methods to find these files. First it checks the DAT subdirectory under the directory defined by PIPCSHARE in the pipc.ini file. Next it checks in a directory up one level and back down into a directory called DAT from the current directory. If not found there, the directory specified as PIHOME above is used as the current directory and its DAT subdirectory is searched. Other locations are also searched for backwards compatibility; however it is advisable to have a single instance of these files in the primary location.

The piclient.ini file has historically been used to support the definition of the default server. The pilogin.ini file was introduced with the PI-ProcessBook program to support both default connections and multiple connection management. The file now also supports port definition and node ID’s (a numeric mapping of server nodes used to reduce storage and provide server and application mobility). Currently the PI-API will search for either of these files for connection information. The pilogin.ini is preferred and if found will be used. The piclient.ini file is supported for backwards compatibility. Typical .ini files are shown below. During installation, these files are installed in the PIHOME DAT subdirectory and should be edited to reflect the user’s servers and login names, described below.

The standard .ini file format is composed of sections (surrounded by brackets), items (to the left of an = sign) and values (to the right of an = sign). All lines beginning with a semicolon (;) are comments only.

PILOGIN.INI

[Services]

PI1=PI

[PINodeIdentifiers]

; Servername, NodeID, Port#

PI1=MYVMSSERVER,34618,545

PI2=MYNTSERVER,85776,5450

HELPFILE=C:\PIPC\LIBRARY\PILOGIN.HLP

[Defaults]

; The default server name

PIServer=MYVMSSERVER

; The user names for the servers above

PI1USER=newuser

PI2USER=newuser

;[WINSOCK]

; Uncomment for DEC Pathworks version 5

;AF=DECnet

PICLIENT.INI

[PISERVER]

PIHOMENODE=MYVMSSERVER

PILOGIN.INI

The pilogin.ini file must be edited by hand using Notepad or similar editor if only the PI-API is installed on a machine. Users who have one of OSI’s client products, such as PI-ProcessBook, or PI-DataLink, can use the Connections dialog in these programs to add, modify, and delete server entries in the file. This approach is preferred as it will generate compatible node identifiers (discussed below) on different PCs connecting to the same server.

The pilogin.ini file contains information for multiple connections. Each connection is given a sequential identifier (e.g., PI1, PI2, ... PIn) and this identifier is used across sections to identify different aspects of the same connection.

The Services section contains the type of service supported for each connection. Currently only PI is a valid entry here. Only a single entry is required.

The PINodeIdentifiers section contains sets of server name, nodeID, and port number separated by commas, one entry for each connection. These should be edited to reflect the desired server names, nodeIDs, and ports as discussed below.

The Defaults section contains the name of the default server as the value associated with the PIServer item. This should be modified to reflect the local default server. Following the default server are the default user names for each connection. Again these should be modified to reflect the local environment. The HELPFILE entry indicates the location of the Login Services help file and should be set to reflect the installed PIHOME location.

Finally, under the WinSock section there is a commented out entry specifying AF (address family) = DECNet. This should only be uncommented for systems using DEC Pathworks version 5 to connect to a PI server which is not running TCP/IP.

Node Identifiers

In the example above two servers are specified, MYNTSERVER and MYVMSSERVER. MYVMSSERVER is at port 545, which is standard for all Open VMS servers. MYNTSERVER is at 5450, which is typical of Windows NT and UNIX servers. Port numbers are used for TCP/IP connections.

The nodeID (34618 for MYVMSSERVER above) is used to give a numeric alias to the server. This may be used by applications to promote moving applications to different servers or replacing or moving of PI systems among servers. For example, if an application stores significant points, it will likely need to store a reference to the server where this point resides.

Applications that store many such points save significant space and processing time using a numeric representation. In addition an application, by using the pilogin.ini file to establish server names from stored nodeIDs, can handle the PI system moving to a new server simply by editing the pilogin.ini file to reflect the new mapping and retaining all the internal nodeID information about the location of the data.

Note: It is a good idea to use a consistent set of node IDs throughout a site, only changing them to reflect server changes.

The connection dialog, now supported in PI-API’s PILOGIN services and recent releases of PI Windows products (ProcessBook, PIPC) provides a user interface for adding new connections which generates a unique nodeID based on the server name. This generated nodeID can be edited to align the nodeID with previously established site standards.

PICLIENT.INI

The piclient.ini file is used if a pilogin.ini file cannot be found. The piclient.ini file above indicates that a PI program under Windows will resolve remote PI function calls with the PIServer named MYVMSSERVER by default. Default connections are made if the PI program calls the piut_connect function, calls the function piut_setservernode with a NULL string or calls server interface functions without calling for a connection first. Again, the piclient.ini file is only used for this purpose if the pilogin.ini file cannot be found or older versions of the PI-API are being used.

Building and Running Applications

Compilation with Predefined Constants

Certain predefined constants are required for successful programming with the PI-API. Your compiler may automatically define these or provide a means to define constants for all compiled modules. If not, these defines must be included in your source before the PI-API header files are included.

For this platform the required constants are:

-D_WINDOWS  Windows specific behavior

-DDOS Windows specific behavior

Linking

DLLs

On the MS Windows platform, each PI-API application, when running, must use its own distinct copy of the PI-API library. For this reason, only a single application using the installed piapi.dll may be run at one time.

MS Windows, when requested to load a DLL, checks to see if the required DLL is already loaded using the internal library name. Simply copying the DLL to a new name is not sufficient to provide a distinct copy of the DLL to Windows.

OSI products that internally make use of the PI-API come with versions of the API named externally and internally as piapixx.dll where xx is a two-character designator for the product. The DLL delivered with the PIAPI is internally named piapi.dll to avoid conflicts with other OSI products.

If calls are made to the PILOGIN services, supported by the pilogin.dll, the program must also link with the pilogin.lib import library. A single pilogin.dll supports all running 16-bit PI-API programs.

Example Programs

C/C++

The file apisnap.mak in \PIPC\EXAMPLES\C is a Visual C++ compatible makefile that builds a program that obtains the current value for a tag. If you are developing in MSVC, it is useful to review this program and the compiler settings established by the makefile.

Visual Basic

PI programs developed with Visual Basic should contain the file piapi.bas as a module in the project file. This files contains all required function declarations for calling piapi and pilogin functions from Visual Basic. See Calling PI-API Functions from Visual Basic. The file, piutil.bas, provides various utility routines which may be used directly or as examples. Two Visual Basic example programs are also provided, Monitor, and ManInput in the directory PIPC\EXAMPLES\BASIC\.

Execution

To successfully execute, the default PIServer needs to be defined in the initialization files and the pipc.ini file must exist in the Windows directory with the PIHOME entry in the PIPC section pointing to the PIPC directory. (See the installation and initialization file sections above.)

Log File

When a connection fails between the server and the PC or other problems occur, messages are written to a local log file. This file is called pipc.log and is located in the \PIPC\DAT directory. The function pilg_putlog also outputs to this file. If the PIHOME directory cannot be determined, (pipc.ini file incorrect or missing) the log file is written to the directory defined in the TEMP environment variable. When connection troubles are encountered, consult the pipc.log file for more information.

Pathworks Version 5.0

Pathworks version 5 WinSock implementation supports INET address format (TCP/IP) and DECNet address format (DECNet). Therefore it is possible to access both DECNet and TCP/IP via WinSock. The default behavior of WinSock PI-API is to first attempt TCP/IP startup; if this fails, DECNet startup is attempted.

Clients with TCP/IP and DECNet installed which require DECNet PIHOME connections can override this behavior. This is accomplished by adding the following two lines to PICLIENT.INI:

[WINSOCK]

AF=DECnet

Enabling Operational Intelligence