The API for IDL does not update !MDS_SOCKET correctly

[mwinkel-dev]

Affiliation
MIT PSFC

Version(s) Affected
client and server = alpha-7-157-0, but likely exists in all recent versions

Platform(s)
macOS (Apple Silicon) but surely exists on all other platforms

Installation Method(s)
developer build

Describe the bug
MDSplus provides an API for the IDL programming language. The API uses an internal "system variable" (i.e., global variable) named !MDS_SOCKET. The conjecture is that it is supposed to have the "connection ID" of the most recent connection to an mdsip process. However, it is not being updated consistently.

This output illustrates the issue. (Note that socket=conn_id means that the socket keyword to the procedure will return the new socket in the conn_id variable. In IDL, keyword variables can be input and/or output.)

IDL>
IDL> ; The system variable belongs to the MDSplus API for IDL, thus doesn’t exist
IDL> ; prior to calling the API.
IDL> print, !MDS_SOCKET
% Not a legal system variable: !MDS_SOCKET.
% Execution halted at: $MAIN$          
IDL>
IDL> ; Valid connection IDs start at 0, and then increment 
IDL> mdsconnect, 'localhost'
% Compiled module: MDSCONNECT.
% Compiled module: MDS_KEYWORD_SET.
% Compiled module: MDSDISCONNECT.
IDL> print, !MDS_SOCKET
       0
IDL> 
IDL> mdsconnect, 'localhost'
IDL> print, !MDS_SOCKET
       1
IDL> 
IDL> mdsconnect, 'localhost'
IDL> print, !MDS_SOCKET
       2
IDL> 
IDL> ; Note that the current connection is 3, but !MDS_SOCKET is stuck at 2
IDL> conn_id = -1
IDL> mdsconnect, 'localhost', socket=conn_id
IDL> print, !MDS_SOCKET, conn_id
       2           3
IDL> 
IDL> mdsconnect, 'localhost', socket=conn_id
IDL> print, !MDS_SOCKET, conn_id
       2           4
IDL> 
IDL> ; Disconnected from connection 4
IDL> mdsdisconnect, socket=conn_id
IDL> print, !MDS_SOCKET, conn_id
       2           4
IDL> 
IDL> ; Connection 4 no longer exists, thus surprising not reused when reconnect
IDL> mdsconnect, 'localhost', socket=conn_id
IDL> print, !MDS_SOCKET, conn_id
       2           5
IDL>
IDL> ; Disconnecting this way resets !MDS_SOCKET to -1 = INVALID_CONNECTION_ID .
IDL> ; Furthermore, it is unclear which connection ID was disconnected.
IDL> mdsdisconnect
IDL> print, !MDS_SOCKET, conn_id
      -1           5
IDL> .
IDL> ; !MDS_SOCKET still indicates INVALID_CONNECTION_ID even though just reconnected
IDL> mdsconnect, 'localhost', socket=conn_id
IDL> print, !MDS_SOCKET, conn_id
      -1           6
IDL> 
IDL> ; Now, !MDS_SOCKET jumps to 7 simply because didn’t use the “socket” keyword
IDL> mdsconnect, 'localhost'
IDL> print, !MDS_SOCKET, conn_id
       7           6

To Reproduce

• If running mdsip on the same computer that has IDL, then use 'localhost' as the server. Otherwise, use the name of the remote archive server.
• Run the commands as shown in the above example.

Expected behavior
Conjecture is that the !MDS_SOCKET variable should always be set to the most recently created connection ID.

Screenshots
n/a

Additional context
When investigating this issue, first determine where !MDS_SOCKET is used and read. In particular, determine if there is a reason for !MDS_SOCKET to not track the current connection ID.

[mwinkel-dev]

The Python "thin client" also has connection IDs that always increment (I.e., never reuse a disconnected ID). So, additional investigation must be done to determine why this is so. (The code in Connections.c must be studied.)

>>> import MDSplus as mds
>>> c = mds.Connection('localhost')
>>>> print(c.conn._conid)
0
>>> d = mds.Connection('localhost')
>>> print(d.conn._conid)
1
>>> e = mds.Connection('localhost')
>>> print(e.conn._conid)
2
>>> e.disconnect()
>>> 
>>> f = mds.Connection('localhost')
>>> print(f.conn._conid)
3
>>> c.disconnect()
>>> 
>>> g = mds.Connection('localhost')
>>> print(g.conn._conid)
4

Regardless, the main issue with the API for IDL is the mystery associated with the erratic update of !MDS_SOCKET.

[mwinkel-dev]

Experiments prove that when a new connection is established, it is never assigned the "connection ID" of a previously disconnected connection. This applies to all APIs provided by MDSplus.

The API for IDL has some similarities to the API for C. Namely, the MdsOpen() and MdsClose() commands cannot be applied to specific connection IDs. (The two IDL procedures do not accept the socket keyword.) Thus, they instead obtain the connection ID from a global variable, !MDS_SOCKET, that contains the ID for the most recently established connection.

Interestingly though, the IDL function, MdsValue(), does accept the optional socket keyword, thus in some circumstances it is possible for IDL to have multiple active connections. The following example shows IDL opening connections to three different servers and then obtaining the MDSplus version of each server.

IDL> CD, '/usr/local/mdsplus/lib'
IDL> cid1 = -1
IDL> cid2 = -1
IDL> cid3 = -1
IDL> mdsconnect, 'localhost', socket=cid1
% Compiled module: MDSCONNECT.
% Compiled module: MDS_KEYWORD_SET.
IDL> mdsconnect, '<server2>', socket=cid2
IDL> mdsconnect, '<server3>', socket=cid3
IDL> print, cid1, cid2, cid3
           0           1           2
IDL> mdsvalue('Tcl("show version", _ver); _ver', socket=cid1)
% Compiled module: MDSVALUE.
% Compiled module: MDSCHECKARG.
% Compiled module: MDSISCLIENT.


MDSplus version: 7.157.0
----------------------
  Release:  alpha_release-7-157-0
  Date:     Fri Dec 05 23:13:40 UTC 2025
  Browse:   https://github.com/MDSplus/mdsplus/tree/alpha_release-7-157-0
  Download: https://github.com/MDSplus/mdsplus/releases/tag/alpha_release-7-157-0



IDL> mdsvalue('Tcl("show version", _ver); _ver', socket=cid2)


MDSplus version: 7.139.67
----------------------
  Release:  alpha_release_7.139.67
  Browse:   https://github.com/MDSplus/mdsplus/tree/alpha_release_7.139.67
  Download: https://github.com/MDSplus/mdsplus/archive/alpha_release_7.139.67.tar.gz



IDL> mdsvalue('Tcl("show version", _ver); _ver', socket=cid3)


MDSplus version: 7.154.0
----------------------
  Release:  alpha_release-7-154-0
  Date:     Fri Oct 10 22:02:02 UTC 2025
  Browse:   https://github.com/MDSplus/mdsplus/tree/alpha_release-7-154-0
  Download: https://github.com/MDSplus/mdsplus/releases/tag/alpha_release-7-154-0



IDL> 

[mwinkel-dev]

IMPORTANT:
There are two system variables (i.e., globals), !MDS_SOCKET and !MDSDB_SOCKET, and they are not independent. The set_database.pro file has a MDSDbConnect function that also calls mdsconnect.

Thus, the intent is apparently as follows:

• !MDS_SOCKET should contain the last connection to an MDSplus archive server.
• !MDSDB_SOCKET should contain the last connection to a relational database server (such as that used for the Logbook application). This opens an mdsip connection to MDSplus running on the RDBMS server, whereupon the remote MDSplus execute's TDI's DSQL() function (and related functions) to access the database.

That likely invalidates the assumption of this entire issue. After more investigation, the likely outcome of this issue is to leave the existing IDL API "as is", and instead ensure that the documentation clearly describes the behavior of the connection IDs and the two system variables: !MDS_SOCKET and !MDSDB_SOCKET.

[mwinkel-dev]

To have !MDS_SOCKET track connections just to MDSplus archive servers and !MDSDB_SOCKET track connections just to database servers, it is necessary to add an optional database keyword to the MdsConnect procedure of the API for IDL. (In essence, the existing socket keyword was being overloaded to also convey that a database connection was being made. However, that usage was not documented, and thus it is clearer to have a separate database keyword.)

[mwinkel-dev]

This issue can be closed when PR #3009 is reviewed and merged.