home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / lansystk.zip / BOOKS / READAPI.DOC
Text File  |  1998-05-08  |  18KB  |  851 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.                                                          IBM LAN Systems
  18.                                                           LAN SERVER API
  19.                                                          SAMPLE PROGRAMS
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.      CONTENTS
  31.  
  32.  
  33.        LAN SYSTEMS API TOOLKIT SAMPLE PROGRAMS . . . . . . . . . . . . 1
  34.        PROGRAMMING ENVIRONMENT   . . . . . . . . . . . . . . . . . . . 1
  35.        PROGRAMMING STYLE   . . . . . . . . . . . . . . . . . . . . . . 2
  36.        PROGRAM FILES   . . . . . . . . . . . . . . . . . . . . . . . . 3
  37.  
  38.        LAN SYSTEMS API TOOLKIT SAMPLE PROGRAMS FOR LAN SERVER  . . . . 4
  39.        ACCSINFO  . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
  40.        FILEENUM  . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
  41.        ML  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
  42.        MLOGON  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
  43.        SADMCMD   . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
  44.        SHAREDEL   . . . . . . . . . . . . . . . . . . . . . . . . . . 10
  45.        STATS  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
  46.        STATS32  . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.                                                             Contents i
  84.  
  85.  
  86.  
  87.  
  88.  
  89.      LAN SYSTEMS API TOOLKIT SAMPLE PROGRAMS
  90.  
  91.      This document contains descriptions of sample programs that use the
  92.      OS/2 LAN Server 3.0 application programming interfaces (LAN APIs).
  93.  
  94.  
  95.      PROGRAMMING ENVIRONMENT
  96.  
  97.      All of the sample programs have been compiled using the following:
  98.  
  99.      ■  IBM OS/2 Verison 2.1
  100.  
  101.      ■  IBM C/C++ Set/2 Version 2.01
  102.  
  103.      ■  IBM OS/2 Toolkit Version 2.1
  104.  
  105.      ■  IBM LAN Systems API Toolkit
  106.  
  107.      Note:
  108.  
  109.      To successfully compile the sample programs, the compiler
  110.      environment varibles LIB and INCLUDE must be changed to contain
  111.      entries for the LS API Toolkit.  This change may be done in
  112.      CONFIG.SYS by altering the LIB and INCLUDE statements, as follows:
  113.  
  114.      ■  LIB=...;c:\LSAPITK\OS2\LIB;...
  115.  
  116.      ■  INCLUDE=...;c:\LSAPITK\OS2\INCLUDE;...
  117.  
  118.      Or they could be changed on the command line for the current session
  119.      using the SET command, as follows:
  120.  
  121.      ■  SET LIB=c:\LSAPITK\OS2\LIB;%LIB%
  122.  
  123.      ■  SET INCLUDE=c:\LSAPITK\OS2\INCLUDE;%INCLUDE%
  124.  
  125.      Note that this assumes that the LS API ToolKit was installed at
  126.      the root of the C: drive.  If the Toolkit was installed on another
  127.      drive or path the c: in the above examples would have to be changed
  128.      to reflect the difference.
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.                                            PROGRAMMING ENVIRONMENT   1
  143.  
  144.  
  145.  
  146.  
  147.  
  148.      PROGRAMMING STYLE
  149.  
  150.      The programs use some common OS/2 conventions:
  151.  
  152.      ■  Standard OS/2 variable naming conventions.  Each variable has a
  153.         lowercase prefix that indicates the variable type. For example,
  154.         pchBuf is a pointer of type char or PCHAR.
  155.  
  156.      ■  Standard OS/2 definitions for variables.  For example, PUSHORT
  157.         pusRc < = > unsigned short *pusRc.
  158.  
  159.      The definitions are contained in the OS2DEF.H file.  This file is
  160.      installed with "OS/2 Developer's Toolkit".
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.                                                    Programming Style 2
  202.  
  203.  
  204.  
  205.  
  206.  
  207.      MAKEFILE AND SOURCE CODE FILES
  208.  
  209.      Program listings include makefiles and source code files.  The
  210.      types of files are :
  211.  
  212.      ■  PROGRAM.MAK - IBM C Set/2 NMAKE make file
  213.  
  214.      ■  PROGRAM.DEF - Module definition file
  215.  
  216.      ■  PROGRAM.H - Program-specific include file
  217.  
  218.      ■  PROGRAM.C - C source code listing
  219.  
  220.      ■  PROGRAM.DLG - Presentation Manager dialogue definition file
  221.  
  222.      ■  PROGRAM.RC - Presentation Manager resource compiler definition
  223.         file.
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                                       PROGRAM FILES  3
  261.  
  262.  
  263.  
  264.  
  265.      LAN SYSTEMS API TOOLKIT SAMPLE PROGRAMS FOR OS/2 LAN SERVER
  266.  
  267.      There are eight short sample programs in the Toolkit that are
  268.      intended to provide an introduction to, and demonstrate the use
  269.      of, the individual API functions.
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.          LAN SYSTEMS API TOOLKIT SAMPLE PROGRAMS FOR OS/2 LAN SERVER 4
  320.  
  321.  
  322.  
  323.      ACCSINFO
  324.  
  325.      ACCSINFO returns the audit profile and all access control profiles
  326.      (ACPs) for a particular resource. The user may alter the auditing
  327.      level and any given ACP.
  328.  
  329.      This program can operate both locally and remotely. The machine
  330.      running this program must be logged on to the LAN with
  331.      administrator authority.
  332.  
  333.      The syntax of the call is as follows.
  334.  
  335.       For a remote server:
  336.                  accsinfo <servername> <resourcename>
  337.  
  338.       For a local server:
  339.                  accsinfo <resourcename>
  340.  
  341.       Where
  342.                  servername = \\<server machinename>
  343.                  resourcename = <drive>:\\<pathname>
  344.                             or   \\pipe\\<pipename>
  345.                             or   \\print\\<queuename>
  346.  
  347.      ACCSINFO uses the NetAPI functions NetAccessGetInfo and
  348.      NetAccessSetInfo.
  349.  
  350.      Two separate calls are performed to use the NetAccessGetInfo
  351.      function.  In the first call, a zero-byte information buffer is
  352.      provided.  This guarantees that NetAccessGetInfo cannot return
  353.      successfully.  Instead it returns with an error return code of
  354.      NERR_BufTooSmall.  However, a valid Totalavail field is returned,
  355.      which indicates exactly how many bytes of information are
  356.      available.  The proper amount of space can now be allocated for the
  357.      information buffer, and a second call will return a valid
  358.      access_info structure to the buffer.
  359.  
  360.      The following files, required to run this program, are in the
  361.      ACCSINFO subdirectory.
  362.  
  363.      ■  ACCSINFO.MAK - IBM C Set/2 NMAKE makefile.
  364.  
  365.      ■  ACCSINFO.C - C source code for the main program.
  366.  
  367.      ■  ERRMSG.C - C source code for the Error_message function.
  368.  
  369.      The required libraries are :
  370.  
  371.      ■  NETAPI.LIB - NetAPI library
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.                                                             ACCSINFO 5
  379.  
  380.  
  381.  
  382.      FILEENUM
  383.  
  384.      FILEENUM returns information on open files on a specific server.
  385.      You may choose to view a list of all open files or to restrict the
  386.      list by device path or user. Both the path and the user ID may be
  387.      left unspecified to get information on all files opened by all
  388.      users on the specified server.
  389.  
  390.      The syntax of the call is as follows.
  391.  
  392.       For a remote server:
  393.                  fileenum <servername> <basepath> <username>
  394.  
  395.       For a local server:
  396.                  fileenum <NULL> <basepath> <username>
  397.          or
  398.                  fileenum
  399.  
  400.       Where
  401.                  servername = \\<server machinename>
  402.                  basepath = <drive>:\<pathname>
  403.  
  404.      This program must be run by an administrator.  The opened files
  405.      that are to be listed must be on a redirected drive on the target
  406.      server.
  407.  
  408.      FILEENUM uses the NetAPI function NetFileEnum2.  NetFileEnum2 is
  409.      different from every other NetAPI function because it allows access
  410.      of more than 64KB of information.  Using repeated NetFileEnum2
  411.      calls and a special pointer used by the FRK_INIT function,
  412.      NetFileEnum2 retrieves successive 64KB blocks of information.  The
  413.      "OS/2 LAN Server Version 3.0 Application Programmer's Reference"
  414.      contains a brief description of the use of the FRK_INIT function.
  415.  
  416.      The following files, required to run this program, are in the
  417.      FILENUM subdirectory :
  418.  
  419.      ■  FILEENUM.MAK - IBM C Set/2 NMAKE makefile.
  420.  
  421.      ■  FILEENUM.C - C source code for the main program.
  422.  
  423.      ■  ERRMSG.C - C source code for the Error_message function.
  424.  
  425.      The required libraries are :
  426.  
  427.      ■  NETAPI.LIB - NetAPI library
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.                                                              FILENUM 6
  438.  
  439.  
  440.  
  441.      ML
  442.  
  443.      This program logs on a user.  The user name, password (if
  444.      required), and domain name are passed as command line parameters to
  445.      the program.
  446.  
  447.      The syntax of the call is as follows.
  448.  
  449.            ml <username> <password> <domainname>
  450.        or
  451.            ml <username> <domainname>
  452.  
  453.      The following files, required to run this program, are in the
  454.      ML subdirectory:
  455.  
  456.      ■  ML.MAK - IBM C Set/2 NMAKE makefile.
  457.  
  458.      ■  ML.C - Source code for this program.
  459.  
  460.      The required library is:
  461.  
  462.      ■  UPM.LIB - UPM library
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.                                                                   ML 7
  497.  
  498.  
  499.  
  500.      MLOGON
  501.  
  502.      This program logs on a user, waits for the Spacebar to be pressed,
  503.      and logs off the user. The user name, password (if required), and
  504.      domain name are passed as command line parameters to the program.
  505.  
  506.      The syntax of the call is as follows.
  507.  
  508.          mlogon <username> <password> <domainname>
  509.       or
  510.          mlogon <username> <domainname>
  511.  
  512.      The following files, required to run this program, are in the
  513.      MLOGON subdirectory:
  514.  
  515.      ■  MLOGON.MAK - IBM C Set/2 NMAKE makefile.
  516.  
  517.      ■  MLOGON.C - Source code for this program.
  518.  
  519.      The required library is:
  520.  
  521.      ■  UPM.LIB - UPM library
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.                                                               MLOGON 8
  556.  
  557.  
  558.  
  559.      SADMCMD
  560.  
  561.      This program executes a command on a remote or local server. The
  562.      command to be executed on the server is passed as a command line
  563.      parameter to this program, but it must reside on a disk visible to
  564.      the target server.
  565.  
  566.      The syntax of the call is:
  567.  
  568.       sadmcmd \\<targetservername> <command>
  569.  
  570.      SADMCMD uses the NetAPI function NetServerAdminCommand.
  571.  
  572.      The following files, required to run this program, are in the
  573.      SADMCMD subdirectory :
  574.  
  575.      ■  SACMCMD.MAK - IBM C Set/2 NMAKE makefile.
  576.  
  577.      ■  SADMCMD.C - Source code for this program.
  578.  
  579.      The required library is :
  580.  
  581.      ■  NETAPI.LIB - NetAPI library
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.                                                              SADMCMD 9
  615.  
  616.  
  617.  
  618.      SHAREDEL
  619.  
  620.      SHAREDEL is called with a device name and (optionally) a netname.
  621.      The syntax of the call is as follows.
  622.  
  623.       For a remote server:
  624.                  sharedel <servername> <devicename> <netname>
  625.          or
  626.                  sharedel <servername> <devicename>
  627.  
  628.       For a local server:
  629.                  sharedel <devicename> <netname>
  630.          or
  631.                  sharedel <devicename>
  632.  
  633.       Where
  634.                  servername = \\<server machinename>
  635.                  devicename = <devicename> (for example, C: OR LPT1:)
  636.                  netname = <alias name or netname>
  637.  
  638.      SHAREDEL checks that the device is shared and returns basic
  639.      information on the device type.  The user may stop sharing for a
  640.      particular netname associated with that device.
  641.  
  642.      SHAREDEL uses two of the most simple NetAPI functions,
  643.      NetShareCheck and NetShareDel.  There are no NetAPI data structures
  644.      used in this program.
  645.  
  646.      The following files, required to run this program, are in the
  647.      NETAPIFS subdirectory :
  648.  
  649.      ■  SHAREDEL.MAK - IBM C Set/2 NMAKE makefile.
  650.  
  651.      ■  SHAREDEL.C - C source code for the main program.
  652.  
  653.      ■  ERRMSG.C - C source code for the Error_message function.
  654.  
  655.      The required libraries are :
  656.  
  657.      ■  NETAPI.LIB - NetAPI library for the OS/2 program
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.                                                            SHAREDEL 10
  674.  
  675.  
  676.  
  677.      STATS
  678.  
  679.      STATS is designed to be used by an administrator logged on to an
  680.      OS/2 LAN Server or OS/2 LAN Requester.  STATS is a monitor
  681.      program that allows the administrator to obtain statistics on the
  682.      loading and performance of a local or remote OS/2 LAN Server.
  683.  
  684.      The syntax of the call is:
  685.  
  686.              stats \\<servername> <servicename> <options>
  687.       Where
  688.              servername = the name of the server to be monitored.
  689.              servicename - must be SERVER or REQUESTER.  This
  690.                            parameter must be entered in uppercase
  691.                            characters.  The entire name may be entered,
  692.                            or any number of characters (beginning with
  693.                            the first letter) may be entered.
  694.              options - may be
  695.                          R - Reset (clear) statistics at program startup
  696.                          C - Clear statistics at each display interval
  697.                          D - Display the difference between each set of
  698.                              statistics without clearing the statistics
  699.                          T <nn> - Set the display interval to be nn seconds.
  700.  
  701.      STATS uses only one NetAPI function, NetStatisticsGet2.
  702.  
  703.      The NetStatisticsGet2 function retrieves information from both
  704.      the requester and the server portions of a server machine.  Note
  705.      that these two sets of information, even when they are in the
  706.      same machine, are quite different.
  707.  
  708.      The following files, required to run this program, are in the
  709.      STATS subdirectory:
  710.  
  711.      ■  STATS.MAK - IBM C Set/2 NMAKE makefile.
  712.  
  713.      ■  STATS.C - C source code for the main program.
  714.  
  715.      ■  ERRMSG.C - C source code for the Error_message function.
  716.  
  717.      The required library is:
  718.  
  719.      ■  NETAPI.LIB - NetAPI library
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.                                                               STATS 11
  733.  
  734.  
  735.  
  736.      STATS32 : A 32-BIT SAMPLE PROGRAM
  737.  
  738.      In order to provide an example of converting a 16-bit program to
  739.      a 32-bit program that uses the LAN APIs, a 16-bit sample programs,
  740.      STATS, has been converted to a 32-bit program, STATS32.  The
  741.      function of STATS32 is exactly like that of STATS.  That is, it
  742.      is designed to be used by an administrator logged on to an OS/2
  743.      LAN Server or OS/2 LAN Requester.  STATS32 is a monitor program
  744.      that allows the administrator to obtain statistics on the loading
  745.      and performance of a local or remote OS/2 LAN Server.
  746.  
  747.      Note: the STATS sample that is described above, is a native 32bit
  748.      program that calls the 16bit APIs (just like all the othe sample
  749.      programs in the LS API Toolkit.)  The purpose of STATS32 is to
  750.      demonstrate the changes necessary to make a 16bit program into
  751.      a 32bit program.
  752.  
  753.      The syntax of the call is:
  754.  
  755.  
  756.               stats32 \\<servername> <servicename> <options>
  757.       Where
  758.              servername = the name of the server to be monitored.
  759.              servicename - must be SERVER or REQUESTER.  This
  760.                           parameter must be entered in uppercase
  761.                           characters.  The entire name may be entered,
  762.                           or any number of characters (beginning with
  763.                           the first letter) may be entered.
  764.              options - may be
  765.                          R - Reset (clear) statistics at program startup
  766.                          C - Clear statistics at each display interval
  767.                          D - Display the difference between each set of
  768.                              statistics without clearing the statistics
  769.                          T <nn> - Set the display interval to be nn seconds.
  770.  
  771.      STATS32 uses only one NetAPI function, NetStatisticsGet2.
  772.  
  773.      The NetStatisticsGet2 function retrieves information from both
  774.      the requester and the server portions of a server machine.  Note
  775.      that these two sets of information, even when they are in the
  776.      same machine, are quite different.
  777.  
  778.      In order to demonstrate what changes were necessary to convert
  779.      STATS to a 32-bit program, statements in the source file
  780.      (STATS32.C) that were changed from the 16-bit version (STATS.C)
  781.      are marked with $32C; statements that were deleted have been
  782.      commented out and marked with $32D; statements that were added
  783.      are marked with $32A.
  784.  
  785.      For information on calling the LAN APIs, which are 16-bit, from a
  786.      32-bit program, refer to the  "LAN Server Version 3.0 Application
  787.      Programmer's Reference."  In the example program, the makefile
  788.      for STATS32 uses the \DINCL_32 compiler option to allow STATS32
  789.  
  790.  
  791.                                                             STATS32 12
  792.  
  793.  
  794.  
  795.      to call the LAN APIs.  However, the statement "#define INCL_32"
  796.      could have been added to the source program instead, as it is in
  797.      the other sample programs.
  798.  
  799.      For information on writing 32-bit programs, refer to the "IBM C
  800.      Set/2 User's Guide."  For more information on converting 16-bit
  801.      programs to 32-bit programs, refer to the "IBM C Set/2 Migration
  802.      Guide."
  803.  
  804.      The following files, required to run this program, are in the
  805.      32BIT subdirectory:
  806.  
  807.      ■  STATS32.MAK - IBM C Set/2 Version 1.0 makefile.
  808.  
  809.      ■  STATS32.C - C source code for the main program.
  810.  
  811.      ■  ERRMSG32.C - C source code for the Error_message function.
  812.  
  813.      The required library is:
  814.  
  815.      ■  NETAPI.LIB - NetAPI library for the OS/2 program
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.                                                             STATS32 13
  851.